@cleocode/contracts 2026.9.8 → 2026.9.10

package/dist/dispatch/operations-registry.js

@@ -39,8 +39,137 @@ export function defineDomain(_domain, ops) {
 // ---------------------------------------------------------------------------
 // OPERATIONS — the authoritative registry data
 // ---------------------------------------------------------------------------
+// Requirement commands carry JSON on the wire; the SDK validates the typed gate.
+const requirementTaskParam = {
+    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 = [
+    {
+        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',
@@ -275,6 +404,13 @@ export const OPERATIONS = [
         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' },
@@ -303,7 +439,7 @@ export const OPERATIONS = [
                 name: 'limit',
                 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.)',
+                description: 'Maximum number of tasks to return (default 10). --all or --limit 0 returns every match.',
             },
             {
                 name: 'offset',
@@ -1632,6 +1768,35 @@ export const OPERATIONS = [
             },
         ],
     },
+    // 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',
+            },
+        ],
+    },
     // check.archive.stats incoming from admin (T5615)
     {
         gateway: 'query',
@@ -2435,7 +2600,7 @@ export const OPERATIONS = [
                 type: 'string',
                 required: false,
                 description: 'Task type',
-                enum: ['epic', 'task', 'subtask'],
+                enum: ['saga', 'epic', 'task', 'subtask'],
                 cli: { flag: 'type', short: '-t' },
             },
             {
@@ -2488,6 +2653,72 @@ export const OPERATIONS = [
                 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'],
+                cli: { flag: 'kind' },
+            },
+            {
+                name: 'scope',
+                type: 'string',
+                required: false,
+                description: 'Task granularity',
+                enum: ['project', 'feature', 'unit'],
+                cli: { flag: 'scope' },
+            },
+            {
+                name: 'severity',
+                type: 'string',
+                required: false,
+                description: 'Project-authorized severity with transactional signed evidence',
+                enum: ['P0', 'P1', 'P2', 'P3'],
+                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' },
+            },
         ],
     },
     {
@@ -2722,6 +2953,20 @@ export const OPERATIONS = [
                 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' },
+            },
         ],
         inputSchema: tasksUpdateInputContract,
         outputSchema: OUTPUT_CONTRACTS['tasks.update'],
@@ -2792,6 +3037,88 @@ export const OPERATIONS = [
                 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',
+            },
+        ],
+    },
+    {
+        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' },
+            },
+        ],
+    },
+    {
+        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',
+            },
         ],
     },
     {
@@ -4299,7 +4626,27 @@ export const OPERATIONS = [
         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',
@@ -7337,6 +7684,369 @@ export const OPERATIONS = [
             },
         ],
     },
+    {
+        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',
+                required: true,
+                description: 'Task whose document to export',
+            },
+            {
+                name: 'includeAttachments',
+                type: 'boolean',
+                required: false,
+                description: 'Include attachment manifest',
+            },
+            {
+                name: 'includeMemoryRefs',
+                type: 'boolean',
+                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',
+                required: true,
+                description: 'Document search text',
+            },
+            {
+                name: 'ownerId',
+                type: 'string',
+                required: false,
+                description: 'Optional owner scope',
+            },
+            { name: 'limit', type: 'number', required: false, description: 'Maximum matches' },
+            {
+                name: 'type',
+                type: 'string',
+                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',
+                required: true,
+                description: 'Existing document slug to compare',
+            },
+            { name: 'limit', type: 'number', required: false, description: 'Maximum matches' },
+            {
+                name: 'threshold',
+                type: 'number',
+                required: false,
+                description: 'Minimum similarity',
+            },
+            {
+                name: 'allKinds',
+                type: 'boolean',
+                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',
+                required: true,
+                description: 'First attachment reference',
+            },
+            {
+                name: 'attB',
+                type: 'string',
+                required: true,
+                description: 'Second attachment reference',
+            },
+            {
+                name: 'strategy',
+                type: 'string',
+                required: false,
+                description: 'three-way, cherry-pick, or multi-diff',
+            },
+            {
+                name: 'base',
+                type: 'string',
+                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',
+                required: true,
+                description: 'Owner whose documents to rank',
+            },
+            {
+                name: 'query',
+                type: 'string',
+                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', required: true, description: 'Document owner' },
+            {
+                name: 'name',
+                type: 'string',
+                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',
+                required: false,
+                description: 'Publication target: file or pr',
+            },
+            {
+                name: 'ownerId',
+                type: 'string',
+                required: false,
+                description: 'Required for file publication',
+            },
+            {
+                name: 'toPath',
+                type: 'string',
+                required: false,
+                description: 'Required destination for file publication',
+            },
+            {
+                name: 'attachmentId',
+                type: 'string',
+                required: false,
+                description: 'Attachment to publish',
+            },
+            {
+                name: 'slugOrId',
+                type: 'string',
+                required: false,
+                description: 'Required document reference for PR publication',
+            },
+            {
+                name: 'slug',
+                type: 'string',
+                required: false,
+                description: 'Override document slug',
+            },
+            {
+                name: 'type',
+                type: 'string',
+                required: false,
+                description: 'Override document kind',
+            },
+            { name: 'title', type: 'string', required: false, description: 'Override PR title' },
+            { name: 'body', type: 'string', required: false, description: 'Override PR body' },
+            { name: 'base', type: 'string', 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',
+                required: true,
+                description: 'Document reference to publish',
+            },
+            {
+                name: 'slug',
+                type: 'string',
+                required: false,
+                description: 'Override document slug',
+            },
+            {
+                name: 'type',
+                type: 'string',
+                required: false,
+                description: 'Override document kind',
+            },
+            { name: 'title', type: 'string', required: false, description: 'Override PR title' },
+            { name: 'body', type: 'string', required: false, description: 'Override PR body' },
+            { name: 'base', type: 'string', 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', required: true, description: 'Document owner' },
+            {
+                name: 'fromPath',
+                type: 'string',
+                required: true,
+                description: 'Source file path',
+            },
+            {
+                name: 'blobName',
+                type: 'string',
+                required: false,
+                description: 'Document blob name',
+            },
+            {
+                name: 'contentType',
+                type: 'string',
+                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',
+                required: true,
+                description: 'Root directory to scan',
+            },
+            {
+                name: 'dryRun',
+                type: 'boolean',
+                required: false,
+                description: 'Preview without writing',
+            },
+            {
+                name: 'force',
+                type: 'boolean',
+                required: false,
+                description: 'Replace conflicting import mappings',
+            },
+            {
+                name: 'manifestPath',
+                type: 'string',
+                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',
+                required: false,
+                description: 'Document slug whose history to inspect',
+            },
+            {
+                name: 'verify',
+                type: 'boolean',
+                required: false,
+                description: 'Verify the full audit chain',
+            },
+        ],
+    },
     // ── docs.generate (T798) ─────────────────────────────────────────────────
     {
         gateway: 'query',