@cleocode/contracts 2026.6.13 → 2026.6.14

package/src/operations/tasks.ts

@@ -1078,6 +1078,113 @@ export interface TasksReorderDispatchResult {
   totalSiblings: number;
 }
 
+// ---------------------------------------------------------------------------
+// tasks.reorder-rank / tasks.bulk-move / tasks.assignee
+// (T11786 · epic T11556 · E1-GATEWAY-CRUD — bulk task mutate ops Studio's
+// interactive Kanban binds to)
+// ---------------------------------------------------------------------------
+
+/**
+ * Params for `tasks.reorder-rank` — explicit within-column positional ordering.
+ *
+ * Unlike `tasks.reorder` (which moves ONE task to a 1-based index and recomputes
+ * every sibling), this op takes the FULL desired ordering of a sibling/column
+ * scope as a task-ID array and writes each task's `position` to its index in the
+ * array. This is the Kanban "drag a card and the whole column re-ranks" shape:
+ * the client sends the new column order, the op persists it in one pass.
+ *
+ * @task T11786
+ */
+export interface TasksReorderRankParams {
+  /**
+   * Ordered task IDs describing the desired top-to-bottom column order. Each
+   * task's `position` is set to its (1-based) index in this array. All IDs
+   * SHOULD share a sibling scope (same `parentId`); IDs not found are reported
+   * in {@link TasksReorderRankResult.skipped} rather than failing the batch.
+   */
+  orderedIds: string[];
+}
+/**
+ * Result of `tasks.reorder-rank` — within-column rank confirmation.
+ *
+ * @task T11786
+ */
+export interface TasksReorderRankResult {
+  /** Task IDs whose `position` was written, in the new top-to-bottom order. */
+  ranked: string[];
+  /** Task IDs from the request that did not resolve to a task (no-op for these). */
+  skipped: string[];
+  /** Number of tasks re-ranked (= `ranked.length`). */
+  count: number;
+}
+
+/**
+ * Params for `tasks.bulk-move` — atomic status/stage transition for N tasks.
+ *
+ * Moves a set of tasks to a new `status` (and optionally `pipelineStage`) inside
+ * a SINGLE DB transaction — the Kanban "select N cards, drop them in a new
+ * column" shape. Either `status` or `pipelineStage` (or both) MUST be supplied;
+ * an empty target is rejected. All-or-nothing: any failure rolls back every move.
+ *
+ * @task T11786
+ */
+export interface TasksBulkMoveParams {
+  /** Task IDs to move. Non-empty. */
+  taskIds: string[];
+  /** Target lifecycle status applied to every task. */
+  status?: string;
+  /** Target pipeline stage applied to every task (forward-only validation). */
+  pipelineStage?: string;
+}
+/**
+ * Result of `tasks.bulk-move` — atomic multi-move confirmation.
+ *
+ * @task T11786
+ */
+export interface TasksBulkMoveResult {
+  /** Task IDs successfully moved (all-or-nothing — empty only when count is 0). */
+  moved: string[];
+  /** The status applied, when supplied. */
+  status?: string;
+  /** The pipeline stage applied, when supplied. */
+  pipelineStage?: string;
+  /** Number of tasks moved (= `moved.length`). */
+  count: number;
+}
+
+/**
+ * Params for `tasks.assignee` — set/clear a task's first-class assignee.
+ *
+ * A first-class human/owner assignee surface, DISTINCT from the agent
+ * claim/unclaim lock (`tasks.claim` does a conditional atomic claim with
+ * agent-lock semantics; `tasks.assignee` is a direct unconditional set/clear an
+ * operator or Studio board uses). Pass `assignee: null` (or omit it) to clear.
+ *
+ * @task T11786
+ */
+export interface TasksAssigneeParams {
+  /** Task ID whose assignee is being set or cleared. */
+  taskId: string;
+  /**
+   * The assignee to set. `null` / empty / omitted CLEARS the assignee. A
+   * non-empty string assigns the task to that owner.
+   */
+  assignee?: string | null;
+}
+/**
+ * Result of `tasks.assignee` — assignee set/clear confirmation.
+ *
+ * @task T11786
+ */
+export interface TasksAssigneeResult {
+  /** The task ID whose assignee changed. */
+  taskId: string;
+  /** The new assignee value (null when cleared). */
+  assignee: string | null;
+  /** True when an assignee was set; false when it was cleared. */
+  assigned: boolean;
+}
+
 // tasks.relates.add — relatedId is canonical; targetId kept for backward compat (T5149)
 export interface TasksRelatesAddParams {
   taskId: string;
@@ -1469,6 +1576,14 @@ export interface TasksCompleteQueryParams {
    * @saga T10538 (PM-Core V2 agent-trust)
    */
   cancelledChildWaiverReason?: string;
+  /**
+   * Reason for waiving the `E_CLEO_DEPENDENCY` gate when this task's own work
+   * is done but its `depends` edges point at not-yet-terminal tasks (a stale or
+   * over-specified dependency). Recorded to `.cleo/audit/depends-waiver.jsonl`.
+   *
+   * @task T11954 (DHQ-071)
+   */
+  waiveDependsReason?: string;
 }
 /**
  * Result of `tasks.complete` — completion confirmation with unblocked tasks.
@@ -2004,6 +2119,10 @@ export type TasksOps = {
   readonly restore: readonly [TasksRestoreParams, TasksRestoreResult];
   readonly reparent: readonly [TasksReparentQueryParams, TasksReparentDispatchResult];
   readonly reorder: readonly [TasksReorderQueryParams, TasksReorderDispatchResult];
+  // T11786 (epic T11556) — bulk task mutate ops Studio's interactive Kanban binds to.
+  readonly 'reorder-rank': readonly [TasksReorderRankParams, TasksReorderRankResult];
+  readonly 'bulk-move': readonly [TasksBulkMoveParams, TasksBulkMoveResult];
+  readonly assignee: readonly [TasksAssigneeParams, TasksAssigneeResult];
   readonly 'relates.add': readonly [TasksRelatesAddParams, TasksRelatesAddResult];
   readonly 'relates.add-batch': readonly [TasksRelatesAddBatchParams, TasksRelatesAddBatchResult];
   readonly 'relates.remove': readonly [TasksRelatesRemoveParams, TasksRelatesRemoveResult];

package/src/playbook.ts

@@ -58,6 +58,62 @@ export interface PlaybookAgenticNode extends PlaybookNodeBase {
    * Enforced at spawn time by composeSpawnPayload (T1261 PSYCHE E4).
    */
   context_files?: string[];
+  /**
+   * Pin this stage's LLM to a named profile from `llm.profiles` (T11759 · M4).
+   *
+   * When present, the dispatcher resolves the stage's LLM through the E9
+   * chokepoint (`resolveLLMForSystem`) keyed by the cantbook node identity
+   * (`cantbook:<playbook>#<nodeId>`) with this profile name threaded as the
+   * pin — so the named profile's provider/model/credential win over the
+   * background role default. Additive: a node without `profile`/`model`/
+   * `provider` resolves exactly as before.
+   */
+  profile?: string;
+  /**
+   * Pin this stage's LLM to an explicit model id (T11759 · M4).
+   *
+   * A lower-precedence escape hatch than {@link profile}: when no `profile` is
+   * declared the dispatcher threads this model id as the resolution hint. The
+   * runtime never constructs a transport from it — it is a resolution hint
+   * consumed by the Pi runner / model-runner downstream (Gate-13).
+   */
+  model?: string;
+  /**
+   * Pin this stage's LLM to an explicit provider transport (T11759 · M4).
+   *
+   * Paired with {@link model} as the inline escape hatch when no {@link profile}
+   * is declared. A resolution hint only — never used to build a client here.
+   */
+  provider?: string;
+  /**
+   * Per-step skill allowlist enforced at spawn time (T1947 · M4 cantbook
+   * done-gate, Gap E/F).
+   *
+   * When present, the spawned agent's effective skill set is the INTERSECTION
+   * of the agent's resolved skills (the Tier-0/1/2 baseline) and this list — a
+   * skill not in both is dropped. The allowlist can only RESTRICT the baseline,
+   * never expand it: a skill named here that the agent does not already carry is
+   * NOT added. Additive: a node without `allowed_skills` spawns with its full
+   * baseline skill set, exactly as before.
+   *
+   * Enforced by `composeSpawnPayload` (it intersects `resolvedAgent.skills` with
+   * this list). An empty set after intersection is logged as a warning and the
+   * spawn proceeds with no skills.
+   */
+  allowed_skills?: string[];
+  /**
+   * Per-step tool allowlist enforced at spawn time (T1947 · M4 cantbook
+   * done-gate, Gap E/F).
+   *
+   * When present, the spawned agent's effective tool set is the INTERSECTION of
+   * the agent's resolved tool baseline and this list — a tool not in both is
+   * dropped. Like {@link allowed_skills}, this can only RESTRICT the baseline,
+   * never expand it. Additive: a node without `allowed_tools` is unaffected.
+   *
+   * Enforced by `composeSpawnPayload` AFTER the thin-agent guard, so a worker
+   * still cannot acquire a spawn-capable tool it was never granted.
+   */
+  allowed_tools?: string[];
 }
 
 export interface PlaybookDeterministicNode extends PlaybookNodeBase {