@cleocode/contracts 2026.5.122 → 2026.5.124

package/src/dispatch/operations-registry.ts

@@ -9,6 +9,7 @@
  * @since SG-ARCH-SOLID Saga T9831 · E-CLI-BOUNDARY T9833 · T10061
  */
 
+import { DOCS_LIFECYCLE_STATUSES } from '../operations/docs.js';
 import type { CanonicalDomain, Gateway, OperationDef, ParamDef, Tier } from './operation-def.js';
 
 export type { CanonicalDomain, Gateway, OperationDef, ParamDef, Tier };
@@ -76,6 +77,168 @@ export const OPERATIONS: OperationDef[] = [
         required: false,
         description: 'Include IVTR phase chain history in the response',
       },
+      {
+        name: 'relations',
+        type: 'boolean',
+        required: false,
+        description: 'Expand relation/doc lists while preserving compact MVI counts',
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'query',
+    domain: 'tasks',
+    operation: 'traverse',
+    description: 'tasks.traverse (query) — WorkGraph traversal from a task root',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['rootId', 'direction'],
+    params: [
+      {
+        name: 'rootId',
+        type: 'string',
+        required: true,
+        description: 'Root task ID for the traversal',
+        cli: { positional: true },
+      },
+      {
+        name: 'direction',
+        type: 'string',
+        required: true,
+        description: 'Traversal direction to project from the root task',
+        enum: ['ancestors', 'descendants', 'upstream', 'downstream'],
+      },
+      {
+        name: 'maxDepth',
+        type: 'number',
+        required: false,
+        description: 'Maximum traversal depth to include',
+      },
+      {
+        name: 'includeRelations',
+        type: 'boolean',
+        required: false,
+        description: 'Include non-containment relation edges',
+      },
+      { name: 'cursor', type: 'string', required: false, description: 'Opaque pagination cursor' },
+      { name: 'limit', type: 'number', required: false, description: 'Maximum nodes to return' },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'query',
+    domain: 'tasks',
+    operation: 'tree',
+    description: 'tasks.tree (query) — WorkGraph containment tree projection',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['rootId'],
+    params: [
+      {
+        name: 'rootId',
+        type: 'string',
+        required: true,
+        description: 'Root task ID for the tree projection',
+        cli: { positional: true },
+      },
+      {
+        name: 'maxDepth',
+        type: 'number',
+        required: false,
+        description: 'Maximum containment depth to include',
+      },
+      { name: 'cursor', type: 'string', required: false, description: 'Opaque pagination cursor' },
+      { name: 'limit', type: 'number', required: false, description: 'Maximum nodes to return' },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'query',
+    domain: 'tasks',
+    operation: 'rollup',
+    description: 'tasks.rollup (query) — WorkGraph direct and subtree status/type summary',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['rootId'],
+    params: [
+      {
+        name: 'rootId',
+        type: 'string',
+        required: true,
+        description: 'Root task ID for the rollup',
+        cli: { positional: true },
+      },
+      {
+        name: 'expectedDirectRollup',
+        type: 'string',
+        required: false,
+        description: 'Optional serialized expected direct rollup for stale-projection diagnostics',
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'query',
+    domain: 'tasks',
+    operation: 'frontier',
+    description: 'tasks.frontier (query) — WorkGraph ready and blocked frontier under a root',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['rootId'],
+    params: [
+      {
+        name: 'rootId',
+        type: 'string',
+        required: true,
+        description: 'Root task ID for the frontier',
+        cli: { positional: true },
+      },
+      {
+        name: 'role',
+        type: 'string',
+        required: false,
+        description: 'Optional assignee/role lane filter',
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'query',
+    domain: 'tasks',
+    operation: 'workgraph.audit',
+    description:
+      'tasks.workgraph.audit (query) — aggregate WorkGraph hierarchy/traversal/frontier/rollup diagnostics',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['rootId'],
+    params: [
+      {
+        name: 'rootId',
+        type: 'string',
+        required: true,
+        description: 'Root task ID for the WorkGraph audit',
+        cli: { positional: true },
+      },
+      {
+        name: 'maxDepth',
+        type: 'number',
+        required: false,
+        description: 'Maximum descendant depth to include in audit projections',
+      },
+      {
+        name: 'includeRelations',
+        type: 'boolean',
+        required: false,
+        description: 'Include relation-edge diagnostics in the audit result',
+      },
+      { name: 'cursor', type: 'string', required: false, description: 'Opaque pagination cursor' },
+      {
+        name: 'limit',
+        type: 'number',
+        required: false,
+        description: 'Maximum nodes to return in paginated audit projections',
+      },
     ] satisfies ParamDef[],
   },
   {
@@ -274,6 +437,152 @@ export const OPERATIONS: OperationDef[] = [
     requiredParams: [],
     params: [],
   },
+  {
+    gateway: 'query',
+    domain: 'tasks',
+    operation: 'completion.list',
+    description: 'tasks.completion.list (query) — list typed completion criteria results',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['taskId'],
+    params: [
+      {
+        name: 'taskId',
+        type: 'string',
+        required: true,
+        description: 'Task ID to list completion criteria for',
+        cli: { positional: true },
+      },
+      {
+        name: 'status',
+        type: 'string',
+        required: false,
+        description: 'Optional criterion status filter',
+        enum: ['satisfied', 'unsatisfied', 'waived', 'replaced'],
+      },
+      {
+        name: 'kind',
+        type: 'string',
+        required: false,
+        description: 'Optional criterion kind filter',
+        enum: ['text', 'evidence_bound', 'child_task'],
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'query',
+    domain: 'tasks',
+    operation: 'completion.evaluate',
+    description:
+      'tasks.completion.evaluate (query) — evaluate completion readiness with typed AC results',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['taskId'],
+    params: [
+      {
+        name: 'taskId',
+        type: 'string',
+        required: true,
+        description: 'Task ID to evaluate completion readiness for',
+        cli: { positional: true },
+      },
+      {
+        name: 'includeContext',
+        type: 'boolean',
+        required: false,
+        description: 'Include bounded audit context pack',
+      },
+      {
+        name: 'limit',
+        type: 'number',
+        required: false,
+        description: 'Maximum audit context events when context is included',
+      },
+      {
+        name: 'since',
+        type: 'string',
+        required: false,
+        description: 'Lower ISO timestamp bound for audit context',
+      },
+      {
+        name: 'relationDepth',
+        type: 'number',
+        required: false,
+        description: 'Related-task audit context depth',
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'query',
+    domain: 'tasks',
+    operation: 'completion.explain',
+    description: 'tasks.completion.explain (query) — explain completion blockers and stale state',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['taskId'],
+    params: [
+      {
+        name: 'taskId',
+        type: 'string',
+        required: true,
+        description: 'Task ID to explain completion readiness for',
+        cli: { positional: true },
+      },
+      {
+        name: 'includeContext',
+        type: 'boolean',
+        required: false,
+        description: 'Include bounded audit context pack',
+      },
+      {
+        name: 'limit',
+        type: 'number',
+        required: false,
+        description: 'Maximum audit context events when context is included',
+      },
+      {
+        name: 'since',
+        type: 'string',
+        required: false,
+        description: 'Lower ISO timestamp bound for audit context',
+      },
+      {
+        name: 'relationDepth',
+        type: 'number',
+        required: false,
+        description: 'Related-task audit context depth',
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'tasks',
+    operation: 'projection.repair',
+    description:
+      'tasks.projection.repair (mutate) — repair stale completion projection state with typed errors',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['taskId'],
+    params: [
+      {
+        name: 'taskId',
+        type: 'string',
+        required: true,
+        description: 'Task ID whose completion projection should be repaired',
+        cli: { positional: true },
+      },
+      {
+        name: 'dryRun',
+        type: 'boolean',
+        required: false,
+        description: 'Preview repair actions without writing projection state',
+      },
+    ] satisfies ParamDef[],
+  },
   {
     gateway: 'query',
     domain: 'tasks',
@@ -667,6 +976,38 @@ export const OPERATIONS: OperationDef[] = [
     requiredParams: [],
     params: [],
   },
+  {
+    gateway: 'query',
+    domain: 'orchestrate',
+    operation: 'report',
+    description:
+      'orchestrate.report (query) — grouped readiness report: ready, blocked, blockedBy, gate-blocked, invalid (T10631)',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['epicId'],
+    params: [
+      {
+        name: 'epicId',
+        type: 'string',
+        required: true,
+        description: 'Epic ID to generate the report for',
+        cli: { positional: true },
+      },
+      {
+        name: 'page',
+        type: 'number',
+        required: false,
+        description: 'Page number for paginated output (1-indexed, default 1)',
+      },
+      {
+        name: 'pageSize',
+        type: 'number',
+        required: false,
+        description: 'Page size for paginated output (default 50, max 200)',
+      },
+    ],
+  },
   {
     gateway: 'query',
     domain: 'orchestrate',
@@ -2375,7 +2716,8 @@ export const OPERATIONS: OperationDef[] = [
     gateway: 'mutate',
     domain: 'tasks',
     operation: 'saga.create',
-    description: 'tasks.saga.create (mutate) — create a labeled top-level Epic as a Saga',
+    description:
+      'tasks.saga.create (mutate) — create a Saga as a first-class TaskType (type=saga) per ADR-083',
     tier: 0,
     idempotent: false,
     sessionRequired: false,
@@ -2402,6 +2744,13 @@ export const OPERATIONS: OperationDef[] = [
         description: 'Pipe-separated acceptance criteria',
         cli: { flag: 'acceptance' },
       },
+      {
+        name: 'dryRun',
+        type: 'boolean',
+        required: false,
+        description: 'Validate and preview without writing task, relation, or doc rows',
+        cli: { flag: 'dry-run' },
+      },
     ] satisfies ParamDef[],
   },
   {
@@ -2418,7 +2767,7 @@ export const OPERATIONS: OperationDef[] = [
         name: 'sagaId',
         type: 'string',
         required: true,
-        description: 'Saga task ID (must have label=saga)',
+        description: 'Saga task ID (must have type=saga)',
         cli: { positional: true },
       },
       {
@@ -2530,7 +2879,7 @@ export const OPERATIONS: OperationDef[] = [
         name: 'sagaId',
         type: 'string',
         required: true,
-        description: 'Saga task ID (must have label=saga)',
+        description: 'Saga task ID (must have type=saga)',
         cli: { positional: true },
       },
     ] satisfies ParamDef[],
@@ -2565,6 +2914,35 @@ export const OPERATIONS: OperationDef[] = [
       },
     ] satisfies ParamDef[],
   },
+  {
+    // T10637 — migrate parent_id-based Saga membership to groups relations.
+    // Converts Epics whose parent_id points to a type='saga' task into proper
+    // groups relations. Non-Epic tasks are documented as conflicts.
+    gateway: 'mutate',
+    domain: 'tasks',
+    operation: 'saga.migrate-containment',
+    description:
+      'tasks.saga.migrate-containment (mutate) — convert parent_id-based Saga membership to groups relations; idempotent; audits to saga-contain-migration.jsonl',
+    tier: 0,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [
+      {
+        name: 'sagaId',
+        type: 'string',
+        required: false,
+        description: 'Optional saga task ID. Omit to migrate all sagas.',
+        cli: { positional: true },
+      },
+      {
+        name: 'dryRun',
+        type: 'boolean',
+        required: false,
+        description: 'Report what would happen without mutating rows or writing audit log',
+      },
+    ] satisfies ParamDef[],
+  },
   {
     gateway: 'mutate',
     domain: 'tasks',
@@ -6886,6 +7264,7 @@ export const OPERATIONS: OperationDef[] = [
         type: 'string' as const,
         required: true,
         description: 'Slug of the existing attachment to update',
+        cli: { positional: true },
       },
       {
         name: 'file',
@@ -6893,6 +7272,14 @@ export const OPERATIONS: OperationDef[] = [
         required: false,
         description: 'Path to a local file containing the new content',
       },
+      {
+        name: 'allowExternal',
+        type: 'boolean' as const,
+        required: false,
+        description:
+          'Permit --file to resolve outside the canonical project root; required for explicit external/worktree update ingestion.',
+        cli: { flag: 'allow-external' },
+      },
       {
         name: 'content',
         type: 'string' as const,
@@ -6909,15 +7296,32 @@ export const OPERATIONS: OperationDef[] = [
         name: 'status',
         type: 'string' as const,
         required: false,
+        enum: DOCS_LIFECYCLE_STATUSES,
         description:
           'Override the new lifecycle status. Defaults to "draft" on every update. ' +
-          'Valid: draft|proposed|accepted|superseded|archived|deprecated.',
+          `Valid: ${DOCS_LIFECYCLE_STATUSES.join('|')}.`,
+      },
+      {
+        name: 'dryRun',
+        type: 'boolean' as const,
+        required: false,
+        description:
+          'Preview validation and resulting envelope without mutating attachment rows, blob storage, or audit logs.',
+        cli: { flag: 'dry-run' },
+      },
+      {
+        name: 'strict',
+        type: 'boolean' as const,
+        required: false,
+        description:
+          'Fail body-schema diagnostics instead of surfacing advisory warnings before the write.',
       },
       {
         name: 'attachedBy',
         type: 'string' as const,
         required: false,
         description: 'Agent identity that performed the update (defaults to "human")',
+        cli: { flag: 'attached-by' },
       },
     ],
   },
@@ -7516,7 +7920,7 @@ export const OPERATIONS: OperationDef[] = [
     tier: 1,
     idempotent: true,
     sessionRequired: false,
-    requiredParams: ['version', 'epicId'],
+    requiredParams: ['version'],
     params: [
       {
         name: 'version',
@@ -7527,8 +7931,23 @@ export const OPERATIONS: OperationDef[] = [
       {
         name: 'epicId',
         type: 'string',
-        required: true,
-        description: 'Epic task ID whose children scope the release (R-303)',
+        required: false,
+        description:
+          'Epic task ID whose children scope the release (R-303); mutually exclusive with sagaId/taskIds',
+      },
+      {
+        name: 'sagaId',
+        type: 'string',
+        required: false,
+        description:
+          'Saga task ID whose grouped member Epics scope the release; mutually exclusive with epicId/taskIds',
+      },
+      {
+        name: 'taskIds',
+        type: 'array',
+        required: false,
+        description:
+          'Explicit task-list release scope; mutually exclusive with epicId/sagaId (T10088)',
       },
       {
         name: 'scheme',
@@ -8224,4 +8643,80 @@ export const OPERATIONS: OperationDef[] = [
       },
     ] satisfies ParamDef[],
   },
+
+  // ---------------------------------------------------------------------------
+  // T10629 — tasks.context: bounded task-scoped context pack with token budget
+  // ---------------------------------------------------------------------------
+  {
+    gateway: 'query' as const,
+    domain: 'tasks',
+    operation: 'context',
+    description:
+      'tasks.context (query) — bounded context pack for a single task. ' +
+      'Combines identity + acceptance criteria + blockers + attached docs + ' +
+      'graph edges (from tasks.slice) + recent activity within a configurable ' +
+      'token budget, with explicit omission tracking and expansion hints.',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['taskId'],
+    params: [
+      {
+        name: 'taskId',
+        type: 'string' as const,
+        required: true,
+        description: 'Task ID to build context for (e.g. T10629)',
+        cli: { positional: true },
+      },
+      {
+        name: 'budgetTokens',
+        type: 'number' as const,
+        required: false,
+        description: 'Maximum token budget for the returned pack. Default: 1500',
+      },
+      {
+        name: 'includeAcceptance',
+        type: 'boolean' as const,
+        required: false,
+        description: 'Include acceptance criteria in the pack. Default: true',
+      },
+      {
+        name: 'includeBlockers',
+        type: 'boolean' as const,
+        required: false,
+        description: 'Include blocker summary in the pack. Default: true',
+      },
+      {
+        name: 'includeDocs',
+        type: 'boolean' as const,
+        required: false,
+        description: 'Include attached docs in the pack. Default: true',
+      },
+      {
+        name: 'includeEdges',
+        type: 'boolean' as const,
+        required: false,
+        description:
+          'Include graph edges (upstream/downstream/siblings/related) in the pack. Default: true',
+      },
+      {
+        name: 'includeActivity',
+        type: 'boolean' as const,
+        required: false,
+        description: 'Include recent activity (audit log) in the pack. Default: true',
+      },
+      {
+        name: 'activityLimit',
+        type: 'number' as const,
+        required: false,
+        description: 'Maximum number of recent activity events. Default: 10',
+      },
+      {
+        name: 'edgeDepth',
+        type: 'number' as const,
+        required: false,
+        description: 'Maximum depth for graph edges when includeEdges is true. Default: 1',
+      },
+    ] satisfies ParamDef[],
+  },
 ];

package/src/evidence-atom-schema.ts

@@ -200,10 +200,10 @@ export const callsiteCoverageAtomSchema = z.object({
 // ---------------------------------------------------------------------------
 
 /**
- * Strict UUIDv4 regex (lowercase, hyphenated 8-4-4-4-12 with the `4` major
- * version nibble and `[89ab]` variant nibble) per ADR-079-r2 §2.1 ABNF
- * (`ac-uuid` production) and RFC 9562 §5.4. Used by the `satisfies:` atom
- * to validate the target-AC UUID form.
+ * Strict AC UUID regex (lowercase, hyphenated 8-4-4-4-12 with v4/v5 major
+ * version nibble and `[89ab]` variant nibble). T10586 keeps legacy random
+ * UUIDv4 AC ids valid while allowing deterministic UUIDv5-shaped ids derived
+ * from task id + source key.
  *
  * Validators MUST reject mixed-case to prevent silent dedupe failures — the
  * canonical column casing is lowercase per ADR-079-r1 §2.1.
@@ -212,7 +212,7 @@ export const callsiteCoverageAtomSchema = z.object({
  * @adr ADR-079-r2 §2.1
  */
 export const AC_UUID_REGEX =
-  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[45][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 
 /**
  * Positional-alias regex for `satisfies:` atom target-AC identifiers per
@@ -286,10 +286,10 @@ export const satisfiesAtomSchema = z.object({
   targetTaskId: z
     .string()
     .regex(SATISFIES_TASK_ID_REGEX, 'satisfies atom targetTaskId must match /^T[0-9]{1,7}$/'),
-  /** Lowercase UUIDv4 — populated for the canonical form; undefined for alias form. */
+  /** Lowercase UUIDv4/v5 — populated for the canonical form; undefined for alias form. */
   targetAcId: z
     .string()
-    .regex(AC_UUID_REGEX, 'satisfies atom targetAcId must be a lowercase UUIDv4')
+    .regex(AC_UUID_REGEX, 'satisfies atom targetAcId must be a lowercase UUIDv4/v5')
     .optional(),
   /** Positional alias `AC<1-4 digits>` — populated for alias form; undefined for UUID form. */
   targetAcAlias: z
@@ -882,7 +882,7 @@ export function parseEvidenceString(raw: string): EvidenceAtom[] {
           }
         }
 
-        // ac-id is EITHER a strict UUIDv4 OR an AC<digits> alias — exactly one.
+        // ac-id is EITHER a strict UUIDv4/v5 OR an AC<digits> alias — exactly one.
         let targetAcId: string | undefined;
         let targetAcAlias: string | undefined;
         if (AC_UUID_REGEX.test(acIdRaw)) {
@@ -891,8 +891,8 @@ export function parseEvidenceString(raw: string): EvidenceAtom[] {
           targetAcAlias = acIdRaw;
         } else {
           throw new EvidenceParseError(
-            `satisfies atom ac-id "${acIdRaw}" must be either a lowercase UUIDv4 or AC<1-4 digits> in "${chunk}"`,
-            'Use format: satisfies:T1234#AC2 (alias) or satisfies:T1234#<lowercase-uuidv4> (canonical)',
+            `satisfies atom ac-id "${acIdRaw}" must be either a lowercase UUIDv4/v5 or AC<1-4 digits> in "${chunk}"`,
+            'Use format: satisfies:T1234#AC2 (alias) or satisfies:T1234#<lowercase-uuidv4-or-v5> (canonical)',
           );
         }