@cleocode/contracts 2026.9.8 → 2026.9.10

package/src/dispatch/operations-registry.ts

@@ -48,8 +48,138 @@ export function defineDomain(_domain: CanonicalDomain, ops: OperationDef[]): Ope
 // OPERATIONS — the authoritative registry data
 // ---------------------------------------------------------------------------
 
+// Requirement commands carry JSON on the wire; the SDK validates the typed gate.
+const requirementTaskParam: ParamDef = {
+  name: 'taskId',
+  type: 'string',
+  required: true,
+  description: 'Task that owns the requirement gates',
+  cli: { positional: true },
+};
+
 /** The single source of truth for all operations in CLEO. */
 export const OPERATIONS: OperationDef[] = [
+  {
+    gateway: 'mutate',
+    domain: 'tasks',
+    operation: 'req.add',
+    description: 'Add a validated typed requirement gate without executing it',
+    tier: 1,
+    idempotent: false,
+    sessionRequired: true,
+    requiredParams: ['taskId', 'gate'],
+    params: [
+      requirementTaskParam,
+      {
+        name: 'gate',
+        type: 'string',
+        required: true,
+        description: 'AcceptanceGate JSON; must include kind, description and kind-specific fields',
+        cli: { flag: 'gate' },
+      },
+    ],
+    inputSchema: {
+      operation: 'tasks.req.add',
+      schema: {
+        type: 'object',
+        required: ['taskId', 'gate'],
+        additionalProperties: false,
+        properties: {
+          taskId: { type: 'string', minLength: 1 },
+          gate: { type: 'string', minLength: 1 },
+        },
+      },
+      examples: [
+        {
+          name: 'test',
+          value: {
+            taskId: 'T121',
+            gate: '{"kind":"test","command":"node","args":["verify.mjs"],"expect":"exit0","description":"Task harness passes","req":"PARTNER-121"}',
+          },
+        },
+      ],
+    },
+  },
+  {
+    gateway: 'query',
+    domain: 'tasks',
+    operation: 'req.list',
+    description: 'List named typed requirement gates without executing them',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['taskId'],
+    params: [requirementTaskParam],
+    inputSchema: {
+      operation: 'tasks.req.list',
+      schema: {
+        type: 'object',
+        required: ['taskId'],
+        additionalProperties: false,
+        properties: { taskId: { type: 'string', minLength: 1 } },
+      },
+      examples: [{ name: 'task', value: { taskId: 'T121' } }],
+    },
+  },
+  {
+    gateway: 'query',
+    domain: 'tasks',
+    operation: 'req.migrate.preview',
+    description: 'Preview typed-gate migration proposals without writing',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['taskId'],
+    params: [
+      requirementTaskParam,
+      {
+        name: 'apply',
+        type: 'boolean',
+        required: false,
+        description: 'Must be absent or false for preview',
+      },
+    ],
+    inputSchema: {
+      operation: 'tasks.req.migrate.preview',
+      schema: {
+        type: 'object',
+        required: ['taskId'],
+        additionalProperties: false,
+        properties: { taskId: { type: 'string', minLength: 1 }, apply: { const: false } },
+      },
+      examples: [{ name: 'preview', value: { taskId: 'T121', apply: false } }],
+    },
+  },
+  {
+    gateway: 'mutate',
+    domain: 'tasks',
+    operation: 'req.migrate',
+    description: 'Explicitly apply validated typed-gate migration proposals',
+    tier: 1,
+    idempotent: false,
+    sessionRequired: true,
+    requiredParams: ['taskId', 'apply'],
+    params: [
+      requirementTaskParam,
+      {
+        name: 'apply',
+        type: 'boolean',
+        required: true,
+        description: 'Must be true to apply proposals',
+        cli: { flag: 'apply' },
+      },
+    ],
+    inputSchema: {
+      operation: 'tasks.req.migrate',
+      schema: {
+        type: 'object',
+        required: ['taskId', 'apply'],
+        additionalProperties: false,
+        properties: { taskId: { type: 'string', minLength: 1 }, apply: { const: true } },
+      },
+      examples: [{ name: 'apply', value: { taskId: 'T121', apply: true } }],
+    },
+  },
   {
     gateway: 'query',
     domain: 'tasks',
@@ -288,6 +418,13 @@ export const OPERATIONS: OperationDef[] = [
     sessionRequired: false,
     requiredParams: [],
     params: [
+      {
+        name: 'includeArchive',
+        type: 'boolean',
+        required: false,
+        description: 'Include archived rows under the same filters',
+        cli: { flag: 'include-archive' },
+      },
       { name: 'parent', type: 'string', required: false, description: 'Filter by parent task ID' },
       { name: 'status', type: 'string', required: false, description: 'Filter by task status' },
       { name: 'priority', type: 'string', required: false, description: 'Filter by task priority' },
@@ -319,7 +456,7 @@ export const OPERATIONS: OperationDef[] = [
         type: 'number',
         required: false,
         description:
-          'Maximum number of tasks to return (default 10). Use --all to return every match. (--limit 0 also returns every match, but only on this command — prefer --all.)',
+          'Maximum number of tasks to return (default 10). --all or --limit 0 returns every match.',
       },
       {
         name: 'offset',
@@ -1674,6 +1811,36 @@ export const OPERATIONS: OperationDef[] = [
       },
     ] satisfies ParamDef[],
   },
+  // T12308: the typed-gate runner `cleo verify <id> --run`. A query — it
+  // executes the gates and reports them, and records nothing. Documented as
+  // the canonical driver since T768 and emitted into every validation-stage
+  // spawn prompt, but the flag had been dropped from the command.
+  {
+    gateway: 'query',
+    domain: 'check',
+    operation: 'gate.run',
+    description:
+      "check.gate.run (query) — execute a task's typed acceptance gates and report results; persists nothing (T12308)",
+    tier: 1,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['taskId'],
+    params: [
+      {
+        name: 'taskId',
+        type: 'string',
+        required: true,
+        description: 'Task whose typed gates should run',
+        cli: { positional: true },
+      },
+      {
+        name: 'agent',
+        type: 'string',
+        required: false,
+        description: 'Actor attribution recorded on each gate result',
+      },
+    ] satisfies ParamDef[],
+  },
   // check.archive.stats incoming from admin (T5615)
   {
     gateway: 'query',
@@ -2497,7 +2664,7 @@ export const OPERATIONS: OperationDef[] = [
         type: 'string',
         required: false,
         description: 'Task type',
-        enum: ['epic', 'task', 'subtask'] as const,
+        enum: ['saga', 'epic', 'task', 'subtask'] as const,
         cli: { flag: 'type', short: '-t' },
       },
       {
@@ -2550,6 +2717,73 @@ export const OPERATIONS: OperationDef[] = [
         description: 'Initial note entry for the task',
         cli: { flag: 'notes' },
       },
+      {
+        name: 'dependsWaiver',
+        type: 'string',
+        required: false,
+        description: 'Nonempty reason waiving dependencies for explicit critical priority',
+        cli: { flag: 'depends-waiver' },
+      },
+      {
+        name: 'files',
+        type: 'array',
+        required: false,
+        description: 'Associated repository file paths',
+        cli: { flag: 'files' },
+      },
+      {
+        name: 'dryRun',
+        type: 'boolean',
+        required: false,
+        description: 'Preview creation without task or committed audit writes',
+        cli: { flag: 'dry-run' },
+      },
+      {
+        name: 'parentSearch',
+        type: 'string',
+        required: false,
+        description: 'Search term for resolving the parent task',
+        cli: { flag: 'parent-search' },
+      },
+      {
+        name: 'kind',
+        type: 'string',
+        required: false,
+        description: 'Task intent, independent of hierarchy',
+        enum: ['work', 'research', 'experiment', 'bug', 'spike', 'release'] as const,
+        cli: { flag: 'kind' },
+      },
+      {
+        name: 'scope',
+        type: 'string',
+        required: false,
+        description: 'Task granularity',
+        enum: ['project', 'feature', 'unit'] as const,
+        cli: { flag: 'scope' },
+      },
+      {
+        name: 'severity',
+        type: 'string',
+        required: false,
+        description: 'Project-authorized severity with transactional signed evidence',
+        enum: ['P0', 'P1', 'P2', 'P3'] as const,
+        cli: { flag: 'severity' },
+      },
+      {
+        name: 'forceDuplicate',
+        type: 'boolean',
+        required: false,
+        description: 'Bypass duplicate rejection with committed decision provenance',
+        cli: { flag: 'force-duplicate' },
+      },
+      {
+        name: 'autoDecompose',
+        type: 'boolean',
+        required: false,
+        description:
+          "Move the parent's text acceptance criteria onto a new first subtask when they would otherwise block this add (PM-Core V2 design-point 3) (T12298)",
+        cli: { flag: 'auto-decompose' },
+      },
     ] satisfies ParamDef[],
   },
   {
@@ -2785,6 +3019,20 @@ export const OPERATIONS: OperationDef[] = [
         required: false,
         description: 'Remove related-task edges by taskId',
       },
+      {
+        name: 'phase',
+        type: 'string',
+        required: false,
+        description: 'Project-defined phase, independent of pipeline stage',
+        cli: { flag: 'phase' },
+      },
+      {
+        name: 'noAutoComplete',
+        type: 'boolean',
+        required: false,
+        description: 'Disable automatic parent completion',
+        cli: { flag: 'no-auto-complete' },
+      },
     ] satisfies ParamDef[],
     inputSchema: tasksUpdateInputContract,
     outputSchema: OUTPUT_CONTRACTS['tasks.update'],
@@ -2856,6 +3104,90 @@ export const OPERATIONS: OperationDef[] = [
         description: 'taskId parameter',
         cli: { positional: true },
       },
+      {
+        name: 'force',
+        type: 'boolean',
+        required: false,
+        description: 'Allow dependents and orphan children unless cascade is enabled',
+      },
+      {
+        name: 'cascade',
+        type: 'boolean',
+        required: false,
+        description: 'Archive all descendants with the selected task',
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'tasks',
+    operation: 'reconcile-scope',
+    description:
+      'tasks.reconcile-scope (mutate) — sweep a saga/epic subtree for tasks whose scope overlaps and propose merge/absorb/split/link; read-only unless --apply',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['rootId'],
+    params: [
+      {
+        name: 'rootId',
+        type: 'string',
+        required: true,
+        description: 'Saga, epic or other container to sweep (its whole subtree is considered)',
+        cli: { positional: true },
+      },
+      {
+        name: 'apply',
+        type: 'boolean',
+        required: false,
+        description: 'Write the proposed `relates` edges (read-only without it)',
+        cli: { flag: 'apply' },
+      },
+      {
+        name: 'threshold',
+        type: 'number',
+        required: false,
+        description: 'Report pairs at or above this similarity score, 0-1 (default 0.55)',
+        cli: { flag: 'threshold' },
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'tasks',
+    operation: 'decompose',
+    description:
+      'tasks.decompose (mutate) — move a task’s free-text acceptance criteria onto a new first child, turning the leaf into a container (PM-Core V2 design-point 3)',
+    tier: 1,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['taskId'],
+    params: [
+      {
+        name: 'taskId',
+        type: 'string',
+        required: true,
+        description: 'Task whose text acceptance criteria move to a new child',
+        cli: { positional: true },
+      },
+      {
+        name: 'childTitle',
+        type: 'string',
+        required: false,
+        description: 'Title for the child that inherits the criteria (default: the parent’s)',
+      },
+      {
+        name: 'childDescription',
+        type: 'string',
+        required: false,
+        description: 'Description for the child (default: the parent’s)',
+      },
+      {
+        name: 'dryRun',
+        type: 'boolean',
+        required: false,
+        description: 'Preview the move without writing',
+      },
     ] satisfies ParamDef[],
   },
   {
@@ -4402,7 +4734,28 @@ export const OPERATIONS: OperationDef[] = [
     idempotent: false,
     sessionRequired: false,
     requiredParams: [],
-    params: [],
+    params: [
+      {
+        name: 'source',
+        type: 'string',
+        required: false,
+        description: 'Source of the reviewed backfill request.',
+      },
+      { name: 'kind', type: 'string', required: false, description: 'Backfill classification.' },
+      {
+        name: 'targetTable',
+        type: 'string',
+        required: false,
+        description: 'Derived brain_page_nodes target only.',
+      },
+      {
+        name: 'nodeIds',
+        type: 'array',
+        required: false,
+        description:
+          'Exact qualified graph node IDs to stage; all must resolve to missing, eligible typed sources.',
+      },
+    ],
   },
   {
     gateway: 'mutate',
@@ -7555,6 +7908,369 @@ export const OPERATIONS: OperationDef[] = [
       },
     ],
   },
+  {
+    gateway: 'query',
+    domain: 'docs',
+    operation: 'status',
+    description: 'docs.status (query) — inspect published documentation drift',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [],
+  },
+  {
+    gateway: 'query',
+    domain: 'docs',
+    operation: 'export',
+    description: 'docs.export (query) — Export a task document',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['taskId'],
+    params: [
+      {
+        name: 'taskId',
+        type: 'string' as const,
+        required: true,
+        description: 'Task whose document to export',
+      },
+      {
+        name: 'includeAttachments',
+        type: 'boolean' as const,
+        required: false,
+        description: 'Include attachment manifest',
+      },
+      {
+        name: 'includeMemoryRefs',
+        type: 'boolean' as const,
+        required: false,
+        description: 'Include memory references',
+      },
+    ],
+  },
+  {
+    gateway: 'query',
+    domain: 'docs',
+    operation: 'search',
+    description: 'docs.search (query) — Search document content',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['query'],
+    params: [
+      {
+        name: 'query',
+        type: 'string' as const,
+        required: true,
+        description: 'Document search text',
+      },
+      {
+        name: 'ownerId',
+        type: 'string' as const,
+        required: false,
+        description: 'Optional owner scope',
+      },
+      { name: 'limit', type: 'number' as const, required: false, description: 'Maximum matches' },
+      {
+        name: 'type',
+        type: 'string' as const,
+        required: false,
+        description: 'Document kind filter',
+      },
+    ],
+  },
+  {
+    gateway: 'query',
+    domain: 'docs',
+    operation: 'find',
+    description: 'docs.find (query) — Find similar documents',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['similarSlug'],
+    params: [
+      {
+        name: 'similarSlug',
+        type: 'string' as const,
+        required: true,
+        description: 'Existing document slug to compare',
+      },
+      { name: 'limit', type: 'number' as const, required: false, description: 'Maximum matches' },
+      {
+        name: 'threshold',
+        type: 'number' as const,
+        required: false,
+        description: 'Minimum similarity',
+      },
+      {
+        name: 'allKinds',
+        type: 'boolean' as const,
+        required: false,
+        description: 'Compare all document kinds',
+      },
+    ],
+  },
+  {
+    gateway: 'query',
+    domain: 'docs',
+    operation: 'merge',
+    description: 'docs.merge (query) — Preview a document merge',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['attA', 'attB'],
+    params: [
+      {
+        name: 'attA',
+        type: 'string' as const,
+        required: true,
+        description: 'First attachment reference',
+      },
+      {
+        name: 'attB',
+        type: 'string' as const,
+        required: true,
+        description: 'Second attachment reference',
+      },
+      {
+        name: 'strategy',
+        type: 'string' as const,
+        required: false,
+        description: 'three-way, cherry-pick, or multi-diff',
+      },
+      {
+        name: 'base',
+        type: 'string' as const,
+        required: false,
+        description: 'Common ancestor attachment reference',
+      },
+    ],
+  },
+  {
+    gateway: 'query',
+    domain: 'docs',
+    operation: 'rank',
+    description: 'docs.rank (query) — Rank owner documents',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['ownerId'],
+    params: [
+      {
+        name: 'ownerId',
+        type: 'string' as const,
+        required: true,
+        description: 'Owner whose documents to rank',
+      },
+      {
+        name: 'query',
+        type: 'string' as const,
+        required: false,
+        description: 'Optional ranking query',
+      },
+    ],
+  },
+  {
+    gateway: 'query',
+    domain: 'docs',
+    operation: 'versions',
+    description: 'docs.versions (query) — List document versions',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['ownerId'],
+    params: [
+      { name: 'ownerId', type: 'string' as const, required: true, description: 'Document owner' },
+      {
+        name: 'name',
+        type: 'string' as const,
+        required: false,
+        description: 'Optional document name',
+      },
+    ],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'docs',
+    operation: 'publish',
+    description: 'docs.publish (mutate) — Publish a document to a file or pull request',
+    tier: 1,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [
+      {
+        name: 'target',
+        type: 'string' as const,
+        required: false,
+        description: 'Publication target: file or pr',
+      },
+      {
+        name: 'ownerId',
+        type: 'string' as const,
+        required: false,
+        description: 'Required for file publication',
+      },
+      {
+        name: 'toPath',
+        type: 'string' as const,
+        required: false,
+        description: 'Required destination for file publication',
+      },
+      {
+        name: 'attachmentId',
+        type: 'string' as const,
+        required: false,
+        description: 'Attachment to publish',
+      },
+      {
+        name: 'slugOrId',
+        type: 'string' as const,
+        required: false,
+        description: 'Required document reference for PR publication',
+      },
+      {
+        name: 'slug',
+        type: 'string' as const,
+        required: false,
+        description: 'Override document slug',
+      },
+      {
+        name: 'type',
+        type: 'string' as const,
+        required: false,
+        description: 'Override document kind',
+      },
+      { name: 'title', type: 'string' as const, required: false, description: 'Override PR title' },
+      { name: 'body', type: 'string' as const, required: false, description: 'Override PR body' },
+      { name: 'base', type: 'string' as const, required: false, description: 'PR base branch' },
+    ],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'docs',
+    operation: 'publish-pr',
+    description: 'docs.publish-pr (mutate) — Legacy alias for PR publication',
+    tier: 1,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['slugOrId'],
+    params: [
+      {
+        name: 'slugOrId',
+        type: 'string' as const,
+        required: true,
+        description: 'Document reference to publish',
+      },
+      {
+        name: 'slug',
+        type: 'string' as const,
+        required: false,
+        description: 'Override document slug',
+      },
+      {
+        name: 'type',
+        type: 'string' as const,
+        required: false,
+        description: 'Override document kind',
+      },
+      { name: 'title', type: 'string' as const, required: false, description: 'Override PR title' },
+      { name: 'body', type: 'string' as const, required: false, description: 'Override PR body' },
+      { name: 'base', type: 'string' as const, required: false, description: 'PR base branch' },
+    ],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'docs',
+    operation: 'sync',
+    description: 'docs.sync (mutate) — Sync document content from a file',
+    tier: 1,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['ownerId', 'fromPath'],
+    params: [
+      { name: 'ownerId', type: 'string' as const, required: true, description: 'Document owner' },
+      {
+        name: 'fromPath',
+        type: 'string' as const,
+        required: true,
+        description: 'Source file path',
+      },
+      {
+        name: 'blobName',
+        type: 'string' as const,
+        required: false,
+        description: 'Document blob name',
+      },
+      {
+        name: 'contentType',
+        type: 'string' as const,
+        required: false,
+        description: 'Document media type',
+      },
+    ],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'docs',
+    operation: 'import',
+    description: 'docs.import (mutate) — Import classified project documents',
+    tier: 1,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['scanRoot'],
+    params: [
+      {
+        name: 'scanRoot',
+        type: 'string' as const,
+        required: true,
+        description: 'Root directory to scan',
+      },
+      {
+        name: 'dryRun',
+        type: 'boolean' as const,
+        required: false,
+        description: 'Preview without writing',
+      },
+      {
+        name: 'force',
+        type: 'boolean' as const,
+        required: false,
+        description: 'Replace conflicting import mappings',
+      },
+      {
+        name: 'manifestPath',
+        type: 'string' as const,
+        required: false,
+        description: 'Import manifest path',
+      },
+    ],
+  },
+  {
+    gateway: 'query',
+    domain: 'docs',
+    operation: 'audit',
+    description: 'docs.audit (query) — inspect document history or verify audit chain integrity',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [
+      {
+        name: 'slug',
+        type: 'string' as const,
+        required: false,
+        description: 'Document slug whose history to inspect',
+      },
+      {
+        name: 'verify',
+        type: 'boolean' as const,
+        required: false,
+        description: 'Verify the full audit chain',
+      },
+    ],
+  },
   // ── docs.generate (T798) ─────────────────────────────────────────────────
   {
     gateway: 'query',