@cleocode/contracts 2026.5.121 → 2026.5.123

package/dist/dispatch/operations-registry.js

@@ -8,6 +8,7 @@
  *
  * @since SG-ARCH-SOLID Saga T9831 · E-CLI-BOUNDARY T9833 · T10061
  */
+import { DOCS_LIFECYCLE_STATUSES } from '../operations/docs.js';
 // ---------------------------------------------------------------------------
 // Builder helpers
 // ---------------------------------------------------------------------------
@@ -67,6 +68,167 @@ export const OPERATIONS = [
                 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',
+            },
+        ],
+    },
+    {
+        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' },
+        ],
+    },
+    {
+        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' },
+        ],
+    },
+    {
+        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',
+            },
+        ],
+    },
+    {
+        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',
+            },
+        ],
+    },
+    {
+        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',
+            },
         ],
     },
     {
@@ -260,6 +422,150 @@ export const OPERATIONS = [
         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'],
+            },
+        ],
+    },
+    {
+        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',
+            },
+        ],
+    },
+    {
+        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',
+            },
+        ],
+    },
+    {
+        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',
+            },
+        ],
+    },
     {
         gateway: 'query',
         domain: 'tasks',
@@ -647,6 +953,37 @@ export const OPERATIONS = [
         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',
@@ -2324,7 +2661,7 @@ export const OPERATIONS = [
         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,
@@ -2351,6 +2688,13 @@ export const OPERATIONS = [
                 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' },
+            },
         ],
     },
     {
@@ -2367,7 +2711,7 @@ export const OPERATIONS = [
                 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 },
             },
             {
@@ -2476,7 +2820,7 @@ export const OPERATIONS = [
                 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 },
             },
         ],
@@ -2510,6 +2854,34 @@ export const OPERATIONS = [
             },
         ],
     },
+    {
+        // 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',
+            },
+        ],
+    },
     {
         gateway: 'mutate',
         domain: 'tasks',
@@ -6687,6 +7059,7 @@ export const OPERATIONS = [
                 type: 'string',
                 required: true,
                 description: 'Slug of the existing attachment to update',
+                cli: { positional: true },
             },
             {
                 name: 'file',
@@ -6694,6 +7067,13 @@ export const OPERATIONS = [
                 required: false,
                 description: 'Path to a local file containing the new content',
             },
+            {
+                name: 'allowExternal',
+                type: 'boolean',
+                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',
@@ -6710,14 +7090,29 @@ export const OPERATIONS = [
                 name: 'status',
                 type: 'string',
                 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',
+                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',
+                required: false,
+                description: 'Fail body-schema diagnostics instead of surfacing advisory warnings before the write.',
             },
             {
                 name: 'attachedBy',
                 type: 'string',
                 required: false,
                 description: 'Agent identity that performed the update (defaults to "human")',
+                cli: { flag: 'attached-by' },
             },
         ],
     },
@@ -7273,7 +7668,7 @@ export const OPERATIONS = [
         tier: 1,
         idempotent: true,
         sessionRequired: false,
-        requiredParams: ['version', 'epicId'],
+        requiredParams: ['version'],
         params: [
             {
                 name: 'version',
@@ -7284,8 +7679,20 @@ export const OPERATIONS = [
             {
                 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',
@@ -7935,5 +8342,78 @@ export const OPERATIONS = [
             },
         ],
     },
+    // ---------------------------------------------------------------------------
+    // T10629 — tasks.context: bounded task-scoped context pack with token budget
+    // ---------------------------------------------------------------------------
+    {
+        gateway: 'query',
+        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',
+                required: true,
+                description: 'Task ID to build context for (e.g. T10629)',
+                cli: { positional: true },
+            },
+            {
+                name: 'budgetTokens',
+                type: 'number',
+                required: false,
+                description: 'Maximum token budget for the returned pack. Default: 1500',
+            },
+            {
+                name: 'includeAcceptance',
+                type: 'boolean',
+                required: false,
+                description: 'Include acceptance criteria in the pack. Default: true',
+            },
+            {
+                name: 'includeBlockers',
+                type: 'boolean',
+                required: false,
+                description: 'Include blocker summary in the pack. Default: true',
+            },
+            {
+                name: 'includeDocs',
+                type: 'boolean',
+                required: false,
+                description: 'Include attached docs in the pack. Default: true',
+            },
+            {
+                name: 'includeEdges',
+                type: 'boolean',
+                required: false,
+                description: 'Include graph edges (upstream/downstream/siblings/related) in the pack. Default: true',
+            },
+            {
+                name: 'includeActivity',
+                type: 'boolean',
+                required: false,
+                description: 'Include recent activity (audit log) in the pack. Default: true',
+            },
+            {
+                name: 'activityLimit',
+                type: 'number',
+                required: false,
+                description: 'Maximum number of recent activity events. Default: 10',
+            },
+            {
+                name: 'edgeDepth',
+                type: 'number',
+                required: false,
+                description: 'Maximum depth for graph edges when includeEdges is true. Default: 1',
+            },
+        ],
+    },
 ];
 //# sourceMappingURL=operations-registry.js.map