@cleocode/contracts 2026.5.121 → 2026.5.123

package/src/tasks.ts

@@ -15,7 +15,143 @@
  * @epic T1688
  */
 
+import { z } from 'zod';
+import { TASK_STATUSES } from './status-registry.js';
 import type { TaskPriority, TaskStatus } from './task.js';
+import type { TaskRecord } from './task-record.js';
+
+// ---------------------------------------------------------------------------
+// Standard task mutation envelopes (T10608)
+// ---------------------------------------------------------------------------
+
+/** Mutation bucket names shared by task create/update/delete result envelopes. @task T10608 */
+export type TaskMutationBucket = 'created' | 'updated' | 'deleted';
+
+/** Severity for non-fatal warnings emitted by task mutation preflights/results. @task T10608 */
+export type TaskMutationWarningSeverity = 'info' | 'warning';
+
+/**
+ * Non-fatal warning surfaced by a task mutation.
+ *
+ * Warnings are structured so callers can distinguish partial-success hazards
+ * from hard validation errors without string parsing.
+ *
+ * @task T10608
+ */
+export interface TaskMutationWarning {
+  /** Stable machine-readable code, e.g. `duplicate_likely` or `cascade_delete`. */
+  code: string;
+  /** Human-readable explanation of the warning. */
+  message: string;
+  /** Warning severity. Defaults to `warning` when omitted by older producers. */
+  severity?: TaskMutationWarningSeverity;
+  /** Task ID associated with the warning, when known. */
+  taskId?: string;
+  /** Input field associated with the warning, when applicable. */
+  field?: string;
+  /** Batch input index associated with the warning, when applicable. */
+  index?: number;
+}
+
+/**
+ * Dry-run/preflight projection for task mutations.
+ *
+ * Counts are split by verb so `created`, `updated`, and `deleted` result
+ * envelopes can all expose the same dry-run shape while preserving the older
+ * operation-specific count names during migration.
+ *
+ * @task T10608
+ */
+export interface TaskMutationDryRunSummary {
+  /** Always true for a dry-run projection. */
+  dryRun: true;
+  /** Number of entities that would be created by executing the mutation. */
+  wouldCreate: number;
+  /** Number of entities that would be updated by executing the mutation. */
+  wouldUpdate: number;
+  /** Number of entities that would be deleted by executing the mutation. */
+  wouldDelete: number;
+  /** Total affected entities across create/update/delete buckets. */
+  wouldAffect: number;
+  /** Number of specs/entities that passed preflight validation. */
+  validatedCount: number;
+  /** Rows durably inserted during dry-run; always 0. */
+  insertedCount: 0;
+  /** Rows durably updated during dry-run; always 0. */
+  updatedCount: 0;
+  /** Rows durably deleted during dry-run; always 0. */
+  deletedCount: 0;
+  /** Non-fatal preflight warnings. Empty when no warnings were emitted. */
+  warnings: TaskMutationWarning[];
+}
+
+/**
+ * Standard envelope appended to task mutation results.
+ *
+ * Existing operation-specific legacy fields (`task`, `deletedTask`, `changes`,
+ * etc.) remain available, while new consumers can read the normalized buckets.
+ *
+ * @task T10608
+ */
+export interface TaskMutationEnvelope<
+  TCreated = TaskRecord[],
+  TUpdated = TaskRecord[],
+  TDeleted = TaskRecord[],
+> {
+  /** Whether this was a preview-only mutation. */
+  dryRun?: boolean;
+  /** Created task records. Empty for update/delete-only mutations. */
+  created: TCreated;
+  /** Updated task records. Empty for create/delete-only mutations. */
+  updated: TUpdated;
+  /** Deleted task records. Empty for create/update-only mutations. */
+  deleted: TDeleted;
+  /** Total number of live rows/entities affected by the mutation. */
+  affectedCount: number;
+  /** Structured partial-success/preflight warnings. */
+  mutationWarnings: TaskMutationWarning[];
+  /** Standard dry-run projection. Present only for dry-run/preflight responses. */
+  dryRunSummary?: TaskMutationDryRunSummary;
+}
+
+const taskMutationWarningSeveritySchema = z.enum(['info', 'warning']);
+
+/** Zod schema for structured task mutation warnings. @task T10608 */
+export const taskMutationWarningSchema = z.object({
+  code: z.string().min(1),
+  message: z.string().min(1),
+  severity: taskMutationWarningSeveritySchema.optional(),
+  taskId: z.string().min(1).optional(),
+  field: z.string().min(1).optional(),
+  index: z.number().int().nonnegative().optional(),
+});
+
+/** Zod schema for the standardized task mutation dry-run/preflight summary. @task T10608 */
+export const taskMutationDryRunSummarySchema = z.object({
+  dryRun: z.literal(true),
+  wouldCreate: z.number().int().nonnegative(),
+  wouldUpdate: z.number().int().nonnegative(),
+  wouldDelete: z.number().int().nonnegative(),
+  wouldAffect: z.number().int().nonnegative(),
+  validatedCount: z.number().int().nonnegative(),
+  insertedCount: z.literal(0),
+  updatedCount: z.literal(0),
+  deletedCount: z.literal(0),
+  warnings: z.array(taskMutationWarningSchema),
+});
+
+const taskMutationTaskRecordSchema = z.object({ id: z.string().min(1) }).passthrough();
+
+/** Zod schema for the standardized task mutation envelope. @task T10608 */
+export const taskMutationEnvelopeSchema = z.object({
+  dryRun: z.boolean().optional(),
+  created: z.array(taskMutationTaskRecordSchema),
+  updated: z.array(taskMutationTaskRecordSchema),
+  deleted: z.array(taskMutationTaskRecordSchema),
+  affectedCount: z.number().int().nonnegative(),
+  mutationWarnings: z.array(taskMutationWarningSchema),
+  dryRunSummary: taskMutationDryRunSummarySchema.optional(),
+});
 
 // ---------------------------------------------------------------------------
 // TaskView types (canonical task projection consumed by SDK, CLI, and REST)
@@ -152,6 +288,428 @@ export interface TaskView {
   nextAction: TaskViewNextAction;
 }
 
+// ---------------------------------------------------------------------------
+// Completion evaluation types (T10591)
+// ---------------------------------------------------------------------------
+
+export type CompletionCriterionKind = 'text' | 'evidence_bound' | 'child_task';
+
+export type CompletionCriterionStatus = 'satisfied' | 'unsatisfied' | 'waived' | 'replaced';
+
+export type CompletionBlockerReason =
+  | 'missing_evidence_binding'
+  | 'child_not_done'
+  | 'child_cancelled_requires_waiver'
+  | 'child_replacement_not_done'
+  | 'child_missing'
+  | 'done_parent_stale';
+
+/**
+ * Explicit operator waiver for a child-task completion criterion. @task T10592
+ *
+ * Waivers are intentionally criterion-scoped: the same cancelled child may back
+ * multiple parent criteria, and each criterion needs its own reason, actor, and
+ * timestamp for auditable completion rollups.
+ */
+export interface CompletionCriterionWaiver {
+  /** AC row id that is being waived. */
+  criterionAcId: string;
+  /** Child task id referenced by the waived AC row. */
+  childTaskId: string;
+  /** Human/operator rationale for accepting the cancelled child as waived. */
+  reason: string;
+  /** Actor that approved the waiver. */
+  actor: string;
+  /** ISO-8601 timestamp recording when the waiver was approved. */
+  waivedAt: string;
+}
+
+/**
+ * Explicit replacement policy for a child-task completion criterion. @task T10592
+ *
+ * Replacements only satisfy the original criterion when the replacement child is
+ * itself done; otherwise the criterion remains unsatisfied with a replacement
+ * blocker so rollups can distinguish replaced work from waived or satisfied work.
+ */
+export interface CompletionCriterionReplacement {
+  /** AC row id whose original child requirement is replaced. */
+  criterionAcId: string;
+  /** Original child task id referenced by the AC row. */
+  originalChildTaskId: string;
+  /** Replacement child task id that must be done to satisfy this criterion. */
+  replacementChildTaskId: string;
+  /** Human/operator rationale for replacing the original child. */
+  reason: string;
+  /** Actor that approved the replacement. */
+  actor: string;
+  /** ISO-8601 timestamp recording when the replacement was approved. */
+  replacedAt: string;
+}
+
+/** A typed per-AC completion evaluation row. @task T10591 */
+export interface CompletionCriterionEvaluation {
+  /** Stable AC row id from `task_acceptance_criteria.id`. */
+  acId: string;
+  /** Human alias derived from ordinal, e.g. AC1. */
+  alias: string;
+  /** Stored AC text. */
+  text: string;
+  /** Criteria kind from the AC table. */
+  kind: CompletionCriterionKind;
+  /** Whether this criterion is satisfied, unsatisfied, explicitly waived, or replaced. */
+  status: CompletionCriterionStatus;
+  /** Blocking reason when status is unsatisfied. */
+  reason?: CompletionBlockerReason;
+  /** Target child task id for child_task rows. */
+  targetTaskId?: string;
+  /** Observed child task status for child_task rows. */
+  targetTaskStatus?: TaskStatus;
+  /** Explicit waiver metadata when status is `waived`. */
+  waiver?: CompletionCriterionWaiver;
+  /** Explicit replacement metadata when a replacement policy applies. */
+  replacement?: CompletionCriterionReplacement;
+  /** Observed status of the replacement child task, when a replacement policy applies. */
+  replacementTaskStatus?: TaskStatus;
+  /** Number of evidence bindings attached to this AC. */
+  evidenceBindings: number;
+}
+
+export type CompletionStaleReason = 'done_parent_has_unsatisfied_criteria';
+
+/** Lifecycle/audit actions included in completion context packs. @task T10594 */
+export type CompletionHistoryEventAction =
+  | 'task_completed'
+  | 'task_reopened'
+  | 'task_cancelled'
+  | 'task_uncancelled'
+  | 'task_reparented'
+  | 'ac_projection_rebuilt';
+
+/** Task relation bucket for an audit event carried by a completion context pack. @task T10594 */
+export type CompletionHistoryEventRelation = 'self' | 'parent' | 'child' | 'sibling' | 'related';
+
+/** Structured lifecycle/audit event available to completion evaluation. @task T10594 */
+export interface CompletionHistoryEvent {
+  id: string;
+  timestamp: string;
+  action: CompletionHistoryEventAction;
+  taskId: string;
+  relation: CompletionHistoryEventRelation;
+  actor: string;
+  details?: Record<string, unknown>;
+  before?: Record<string, unknown>;
+  after?: Record<string, unknown>;
+}
+
+/** Event counts precomputed for explainCompletion and machine consumers. @task T10594 */
+export interface CompletionContextPackSummary {
+  totalEvents: number;
+  byAction: Record<CompletionHistoryEventAction, number>;
+  byRelation: Record<CompletionHistoryEventRelation, number>;
+  latestEventAt: string | null;
+}
+
+/** Bounded recent lifecycle context sourced from audit_log. @task T10594 */
+export interface CompletionContextPack {
+  taskId: string;
+  generatedAt: string;
+  source: 'audit_log';
+  window: {
+    limit: number;
+    since?: string;
+    relationDepth: number;
+    relatedTaskIds: string[];
+  };
+  events: CompletionHistoryEvent[];
+  summary: CompletionContextPackSummary;
+}
+
+/** Builder query controls for completion context packs. @task T10594 */
+export interface CompletionContextPackOptions {
+  limit?: number;
+  since?: string;
+  relationDepth?: number;
+}
+
+/** Contract-backed aggregate returned by `evaluateCompletion`. @task T10591 */
+export interface CompletionEvaluation {
+  taskId: string;
+  taskStatus: TaskStatus;
+  /** True only when there are no unsatisfied criteria and the parent is not stale. */
+  ready: boolean;
+  stale: boolean;
+  staleReasons: CompletionStaleReason[];
+  /** Optional bounded audit context used by explanation/evaluation consumers. @task T10594 */
+  contextPack?: CompletionContextPack;
+  satisfied: CompletionCriterionEvaluation[];
+  unsatisfied: CompletionCriterionEvaluation[];
+  waived: CompletionCriterionEvaluation[];
+  replaced: CompletionCriterionEvaluation[];
+  totals: {
+    criteria: number;
+    satisfied: number;
+    unsatisfied: number;
+    waived: number;
+    replaced: number;
+  };
+}
+
+/** Human-readable explanation generated from a CompletionEvaluation. @task T10591 */
+export interface CompletionExplanation {
+  taskId: string;
+  ready: boolean;
+  stale: boolean;
+  summary: string;
+  /** Recent lifecycle context referenced by the summary/blockers when available. @task T10594 */
+  contextPack?: CompletionContextPack;
+  blockers: CompletionCriterionEvaluation[];
+}
+
+/** Parameter contract for `tasks.completion.list`. @task T10607 */
+export interface CompletionListParams {
+  /** Task whose completion criteria should be listed. */
+  taskId: string;
+  /** Optional status filter for criteria rows. */
+  status?: CompletionCriterionStatus;
+  /** Optional criterion kind filter. */
+  kind?: CompletionCriterionKind;
+}
+
+/** Result contract for `tasks.completion.list`. @task T10607 */
+export interface CompletionListResult {
+  taskId: string;
+  criteria: CompletionCriterionEvaluation[];
+  totals: CompletionEvaluation['totals'];
+}
+
+/** Parameter contract for `tasks.completion.evaluate`. @task T10607 */
+export interface CompletionEvaluateParams extends CompletionContextPackOptions {
+  /** Task whose completion readiness should be evaluated. */
+  taskId: string;
+  /** Include bounded audit context in the evaluation response. */
+  includeContext?: boolean;
+}
+
+/** Result contract for `tasks.completion.evaluate`. @task T10607 */
+export type CompletionEvaluateResult = CompletionEvaluation;
+
+/** Parameter contract for `tasks.completion.explain`. @task T10607 */
+export interface CompletionExplainParams extends CompletionEvaluateParams {}
+
+/** Result contract for `tasks.completion.explain`. @task T10607 */
+export type CompletionExplainResult = CompletionExplanation;
+
+/** Typed stale-projection error codes returned by `tasks.projection.repair`. @task T10607 */
+export type CompletionProjectionRepairErrorCode =
+  | 'projection_not_stale'
+  | 'criteria_missing'
+  | 'binding_target_missing'
+  | 'repair_conflict';
+
+/** Stale completion-projection repair diagnostic. @task T10607 */
+export interface CompletionProjectionRepairError {
+  code: CompletionProjectionRepairErrorCode;
+  message: string;
+  taskId: string;
+  acId?: string;
+  evidenceAtomId?: string;
+}
+
+/** Parameter contract for `tasks.projection.repair`. @task T10607 */
+export interface CompletionProjectionRepairParams {
+  /** Task whose derived completion projection should be rebuilt/repaired. */
+  taskId: string;
+  /** Preview repair actions without writing projection state. */
+  dryRun?: boolean;
+}
+
+/** Result contract for `tasks.projection.repair`. @task T10607 */
+export interface CompletionProjectionRepairResult {
+  taskId: string;
+  repaired: boolean;
+  dryRun: boolean;
+  staleBefore: boolean;
+  staleAfter: boolean;
+  errors: CompletionProjectionRepairError[];
+}
+
+const completionTaskStatusSchema = z.enum(TASK_STATUSES);
+const completionCriterionKindSchema = z.enum(['text', 'evidence_bound', 'child_task']);
+const completionCriterionStatusSchema = z.enum(['satisfied', 'unsatisfied', 'waived', 'replaced']);
+const completionBlockerReasonSchema = z.enum([
+  'missing_evidence_binding',
+  'child_not_done',
+  'child_cancelled_requires_waiver',
+  'child_replacement_not_done',
+  'child_missing',
+  'done_parent_stale',
+]);
+const completionStaleReasonSchema = z.enum(['done_parent_has_unsatisfied_criteria']);
+const completionProjectionRepairErrorCodeSchema = z.enum([
+  'projection_not_stale',
+  'criteria_missing',
+  'binding_target_missing',
+  'repair_conflict',
+]);
+const completionCriterionWaiverSchema = z.object({
+  criterionAcId: z.string().min(1),
+  childTaskId: z.string().min(1),
+  reason: z.string().min(1),
+  actor: z.string().min(1),
+  waivedAt: z.string().min(1),
+});
+const completionCriterionReplacementSchema = z.object({
+  criterionAcId: z.string().min(1),
+  originalChildTaskId: z.string().min(1),
+  replacementChildTaskId: z.string().min(1),
+  reason: z.string().min(1),
+  actor: z.string().min(1),
+  replacedAt: z.string().min(1),
+});
+
+/** Zod schema for one typed AC completion-result row. @task T10607 */
+export const completionCriterionEvaluationSchema = z.object({
+  acId: z.string().min(1),
+  alias: z.string().min(1),
+  text: z.string(),
+  kind: completionCriterionKindSchema,
+  status: completionCriterionStatusSchema,
+  reason: completionBlockerReasonSchema.optional(),
+  targetTaskId: z.string().min(1).optional(),
+  targetTaskStatus: completionTaskStatusSchema.optional(),
+  waiver: completionCriterionWaiverSchema.optional(),
+  replacement: completionCriterionReplacementSchema.optional(),
+  replacementTaskStatus: completionTaskStatusSchema.optional(),
+  evidenceBindings: z.number().int().nonnegative(),
+});
+
+/** Zod schema for unsatisfied completion criteria. @task T10607 */
+export const unsatisfiedCompletionCriterionSchema = completionCriterionEvaluationSchema.extend({
+  status: z.literal('unsatisfied'),
+  reason: completionBlockerReasonSchema,
+});
+
+const completionTotalsSchema = z.object({
+  criteria: z.number().int().nonnegative(),
+  satisfied: z.number().int().nonnegative(),
+  unsatisfied: z.number().int().nonnegative(),
+  waived: z.number().int().nonnegative(),
+  replaced: z.number().int().nonnegative(),
+});
+const completionContextPackSchema: z.ZodType<CompletionContextPack> = z.object({
+  taskId: z.string().min(1),
+  generatedAt: z.string().min(1),
+  source: z.literal('audit_log'),
+  window: z.object({
+    limit: z.number().int().positive(),
+    since: z.string().min(1).optional(),
+    relationDepth: z.number().int().nonnegative(),
+    relatedTaskIds: z.array(z.string().min(1)),
+  }),
+  events: z.array(
+    z.object({
+      id: z.string().min(1),
+      timestamp: z.string().min(1),
+      action: z.enum([
+        'task_completed',
+        'task_reopened',
+        'task_cancelled',
+        'task_uncancelled',
+        'task_reparented',
+        'ac_projection_rebuilt',
+      ]),
+      taskId: z.string().min(1),
+      relation: z.enum(['self', 'parent', 'child', 'sibling', 'related']),
+      actor: z.string().min(1),
+      details: z.record(z.string(), z.unknown()).optional(),
+      before: z.record(z.string(), z.unknown()).optional(),
+      after: z.record(z.string(), z.unknown()).optional(),
+    }),
+  ),
+  summary: z.object({
+    totalEvents: z.number().int().nonnegative(),
+    byAction: z.record(z.string(), z.number().int().nonnegative()),
+    byRelation: z.record(z.string(), z.number().int().nonnegative()),
+    latestEventAt: z.string().nullable(),
+  }),
+});
+
+/** Zod result contract for `tasks.completion.evaluate`. @task T10607 */
+export const completionEvaluationSchema = z.object({
+  taskId: z.string().min(1),
+  taskStatus: completionTaskStatusSchema,
+  ready: z.boolean(),
+  stale: z.boolean(),
+  staleReasons: z.array(completionStaleReasonSchema),
+  contextPack: completionContextPackSchema.optional(),
+  satisfied: z.array(completionCriterionEvaluationSchema),
+  unsatisfied: z.array(unsatisfiedCompletionCriterionSchema),
+  waived: z.array(completionCriterionEvaluationSchema),
+  replaced: z.array(completionCriterionEvaluationSchema),
+  totals: completionTotalsSchema,
+});
+
+/** Zod result contract for `tasks.completion.explain`. @task T10607 */
+export const completionExplanationSchema = z.object({
+  taskId: z.string().min(1),
+  ready: z.boolean(),
+  stale: z.boolean(),
+  summary: z.string(),
+  contextPack: completionContextPackSchema.optional(),
+  blockers: z.array(completionCriterionEvaluationSchema),
+});
+
+/** Zod params for `tasks.completion.list`. @task T10607 */
+export const completionListParamsSchema = z.object({
+  taskId: z.string().min(1),
+  status: completionCriterionStatusSchema.optional(),
+  kind: completionCriterionKindSchema.optional(),
+});
+
+/** Zod result contract for `tasks.completion.list`. @task T10607 */
+export const completionListResultSchema = z.object({
+  taskId: z.string().min(1),
+  criteria: z.array(completionCriterionEvaluationSchema),
+  totals: completionTotalsSchema,
+});
+
+/** Zod params for `tasks.completion.evaluate` and `tasks.completion.explain`. @task T10607 */
+export const completionEvaluateParamsSchema = z.object({
+  taskId: z.string().min(1),
+  includeContext: z.boolean().optional(),
+  limit: z.number().int().positive().optional(),
+  since: z.string().min(1).optional(),
+  relationDepth: z.number().int().nonnegative().optional(),
+});
+
+/** Zod params for `tasks.completion.explain`. @task T10607 */
+export const completionExplainParamsSchema = completionEvaluateParamsSchema;
+
+/** Zod schema for typed stale-projection repair errors. @task T10607 */
+export const completionProjectionRepairErrorSchema = z.object({
+  code: completionProjectionRepairErrorCodeSchema,
+  message: z.string().min(1),
+  taskId: z.string().min(1),
+  acId: z.string().min(1).optional(),
+  evidenceAtomId: z.string().min(1).optional(),
+});
+
+/** Zod params for `tasks.projection.repair`. @task T10607 */
+export const completionProjectionRepairParamsSchema = z.object({
+  taskId: z.string().min(1),
+  dryRun: z.boolean().optional(),
+});
+
+/** Zod result contract for `tasks.projection.repair`. @task T10607 */
+export const completionProjectionRepairResultSchema = z.object({
+  taskId: z.string().min(1),
+  repaired: z.boolean(),
+  dryRun: z.boolean(),
+  staleBefore: z.boolean(),
+  staleAfter: z.boolean(),
+  errors: z.array(completionProjectionRepairErrorSchema),
+});
+
 // ---------------------------------------------------------------------------
 // Task tree node (used by tasks.tree operation)
 // ---------------------------------------------------------------------------