@cleocode/contracts 2026.5.122 → 2026.5.123

package/src/__tests__/workgraph-operation-contracts.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Contract tests for the PM-Core V2 WorkGraph dispatch surface.
+ *
+ * @task T10606
+ * @saga T10538
+ */
+
+import { describe, expect, it } from 'vitest';
+import { OPERATIONS } from '../dispatch/operations-registry.js';
+import {
+  tasksFrontierParamsSchema,
+  tasksFrontierResultSchema,
+  tasksRollupParamsSchema,
+  tasksRollupResultSchema,
+  tasksTraverseParamsSchema,
+  tasksTraverseResultSchema,
+  tasksTreeParamsSchema,
+  tasksTreeResultSchema,
+  tasksWorkGraphAuditParamsSchema,
+  tasksWorkGraphAuditResultSchema,
+} from '../workgraph.js';
+
+const requiredOperations = ['traverse', 'tree', 'rollup', 'frontier', 'workgraph.audit'] as const;
+
+function operation(name: (typeof requiredOperations)[number]) {
+  const def = OPERATIONS.find(
+    (candidate) => candidate.domain === 'tasks' && candidate.operation === name,
+  );
+  if (def === undefined) throw new Error(`missing tasks.${name}`);
+  return def;
+}
+
+describe('WorkGraph operation contract schemas', () => {
+  it('validates params and results for every WorkGraph read operation', () => {
+    expect(
+      tasksTraverseParamsSchema.parse({
+        rootId: 'T1',
+        direction: 'descendants',
+        cursor: '0001:T2',
+        limit: 25,
+      }),
+    ).toEqual({
+      rootId: 'T1',
+      direction: 'descendants',
+      cursor: '0001:T2',
+      limit: 25,
+    });
+    expect(
+      tasksTraverseResultSchema.parse({
+        rootId: 'T1',
+        direction: 'descendants',
+        nodes: [],
+        edges: [],
+        pageInfo: { hasMore: false },
+      }).pageInfo.hasMore,
+    ).toBe(false);
+
+    expect(tasksTreeParamsSchema.parse({ rootId: 'T1', maxDepth: 2, limit: 10 })).toEqual({
+      rootId: 'T1',
+      maxDepth: 2,
+      limit: 10,
+    });
+    expect(
+      tasksTreeResultSchema.parse({
+        rootId: 'T1',
+        nodes: [],
+        edges: [],
+        pageInfo: { hasMore: false },
+      }).nodes,
+    ).toEqual([]);
+
+    expect(tasksRollupParamsSchema.parse({ rootId: 'T1' })).toEqual({ rootId: 'T1' });
+    expect(
+      tasksRollupResultSchema.parse({
+        rootId: 'T1',
+        direct: { total: 0, byStatus: {}, byType: {} },
+        subtree: { total: 0, byStatus: {}, byType: {} },
+        percentDenominator: { basis: 'subtree-total', total: 0, description: 'subtree total' },
+        percentages: { done: 0, active: 0, blocked: 0, pending: 0, cancelled: 0 },
+        staleProjection: false,
+        projectionMismatches: [],
+      }).staleProjection,
+    ).toBe(false);
+
+    expect(tasksFrontierParamsSchema.parse({ rootId: 'T1', role: 'worker' })).toEqual({
+      rootId: 'T1',
+      role: 'worker',
+    });
+    expect(
+      tasksFrontierResultSchema.parse({
+        rootId: 'T1',
+        role: 'worker',
+        groups: { ready: [], blocked: [], blockedBy: [] },
+      }).groups.ready,
+    ).toEqual([]);
+
+    expect(
+      tasksWorkGraphAuditParamsSchema.parse({ rootId: 'T1', includeRelations: true, limit: 5 }),
+    ).toEqual({
+      rootId: 'T1',
+      includeRelations: true,
+      limit: 5,
+    });
+    expect(
+      tasksWorkGraphAuditResultSchema.parse({
+        rootId: 'T1',
+        hierarchy: { valid: true, violations: [] },
+        traversal: {
+          rootId: 'T1',
+          direction: 'descendants',
+          nodes: [],
+          edges: [],
+          pageInfo: { hasMore: false },
+        },
+        frontier: { rootId: 'T1', groups: { ready: [], blocked: [], blockedBy: [] } },
+        rollup: {
+          rootId: 'T1',
+          direct: { total: 0, byStatus: {}, byType: {} },
+          subtree: { total: 0, byStatus: {}, byType: {} },
+          percentDenominator: { basis: 'subtree-total', total: 0, description: 'subtree total' },
+          percentages: { done: 0, active: 0, blocked: 0, pending: 0, cancelled: 0 },
+          staleProjection: false,
+          projectionMismatches: [],
+        },
+        relationEdges: { rootId: 'T1', direction: 'both', edges: [] },
+      }).hierarchy.valid,
+    ).toBe(true);
+  });
+
+  it('publishes operation metadata with explicit pagination params', () => {
+    for (const name of requiredOperations) {
+      const def = operation(name);
+      expect(def.gateway).toBe('query');
+      expect(def.domain).toBe('tasks');
+      expect(def.idempotent).toBe(true);
+      expect(def.params ?? []).not.toEqual([]);
+    }
+
+    expect(operation('traverse').requiredParams).toEqual(['rootId', 'direction']);
+    expect(operation('tree').requiredParams).toEqual(['rootId']);
+    expect(operation('rollup').requiredParams).toEqual(['rootId']);
+    expect(operation('frontier').requiredParams).toEqual(['rootId']);
+    expect(operation('workgraph.audit').requiredParams).toEqual(['rootId']);
+
+    for (const name of ['traverse', 'tree', 'workgraph.audit'] as const) {
+      const params = operation(name).params?.map((param) => param.name) ?? [];
+      expect(params).toContain('cursor');
+      expect(params).toContain('limit');
+    }
+  });
+});

package/src/data-accessor.ts

@@ -119,6 +119,14 @@ export interface AcRow {
   taskId: string;
   /** 1-based ordinal — never reused per task (gaps remain on shrink). */
   ordinal: number;
+  /** Typed completion criterion discriminator per ADR-088. */
+  kind: 'text' | 'child_task' | 'evidence_bound';
+  /** Stable per-task source key for idempotent criteria projection/upsert. */
+  sourceKey: string;
+  /** Optional child task target; only `kind='child_task'` may populate it. */
+  targetTaskId: string | null;
+  /** Compatibility projection owner (for example: legacy, direct, parent-child). */
+  projection: string;
   /** The AC statement text. Structured gates are serialised as JSON. */
   text: string;
   /** ISO-8601 timestamp the row was created. */
@@ -129,6 +137,56 @@ export interface AcRow {
   contentHash: string | null;
 }
 
+/** Machine-readable AC child-projection drift codes for doctor/audit output. */
+export type AcProjectionAuditFindingCode =
+  | 'missing_child_task_row'
+  | 'extra_child_task_row'
+  | 'mismatched_child_task_row'
+  | 'stale_child_task_projection';
+
+/** Dirty/clean status for an AC projection audit scan. */
+export type AcProjectionAuditStatus = 'clean' | 'dirty';
+
+/** Field-level child projection mismatch surfaced by doctor/audit callers. */
+export interface AcProjectionAuditFinding {
+  /** Stable machine-readable finding code. */
+  code: AcProjectionAuditFindingCode;
+  /** Parent task whose AC rows were audited. */
+  parentId: string;
+  /** Direct child expected by WorkGraph containment, when applicable. */
+  childId?: string;
+  /** Existing AC row id involved in the finding, when applicable. */
+  acId?: string;
+  /** Compared row field, or `row` for whole-row missing/extra findings. */
+  field: 'row' | 'kind' | 'sourceKey' | 'targetTaskId' | 'projection' | 'text' | 'contentHash';
+  /** Expected canonical value. */
+  expected: string | null;
+  /** Actual observed value. */
+  actual: string | null;
+  /** True when this finding proves cached projection state is dirty/stale. */
+  dirty: true;
+}
+
+/** Typed result returned by AC projection doctor/audit scanners. */
+export interface AcProjectionAuditResult {
+  /** Parent task whose child_task projection rows were audited. */
+  parentId: string;
+  /** Clean when no findings were emitted, dirty otherwise. */
+  status: AcProjectionAuditStatus;
+  /** Boolean convenience flag for CLIs that render dirty state. */
+  dirty: boolean;
+  /** Number of direct children WorkGraph says should be projected. */
+  expectedRows: number;
+  /** Number of existing child_task projection rows observed on the parent. */
+  actualRows: number;
+  /** Stable sha256 over the expected child projection state. */
+  freshnessFingerprint: string;
+  /** True when at least one finding indicates stale/missing/extra projection state. */
+  staleProjection: boolean;
+  /** Typed findings suitable for JSON doctor/audit output. */
+  findings: readonly AcProjectionAuditFinding[];
+}
+
 /**
  * A row of the `evidence_ac_bindings` table (T10503) — the M:N join between
  * evidence atoms and acceptance criteria. Powers the AC-coverage gate
@@ -150,6 +208,26 @@ export interface AcBindingRow {
   createdAt: string;
 }
 
+/** Query options for bounded reads from the append-only task audit log. @task T10594 */
+export interface TaskAuditLogQuery {
+  taskIds?: readonly string[];
+  actions?: readonly string[];
+  since?: string;
+  limit?: number;
+}
+
+/** DataAccessor-facing shape of audit_log rows used by completion context packs. @task T10594 */
+export interface TaskAuditLogRow {
+  id: string;
+  timestamp: string;
+  action: string;
+  taskId: string;
+  actor: string;
+  detailsJson: string | null;
+  beforeJson: string | null;
+  afterJson: string | null;
+}
+
 /**
  * Subset of DataAccessor methods available inside a transaction callback.
  * Write-only — reads use the outer accessor (snapshot isolation).
@@ -160,6 +238,8 @@ export interface TransactionAccessor {
   removeSingleTask(taskId: string): Promise<void>;
   setMetaValue(key: string, value: unknown): Promise<void>;
   updateTaskFields(taskId: string, fields: TaskFieldUpdates): Promise<void>;
+  /** Get direct non-archived children inside the caller-owned transaction. @task T10590 */
+  getChildren(parentId: string): Promise<Task[]>;
   appendLog(entry: Record<string, unknown>): Promise<void>;
   /** Persist a relation row to task_relations. @task T9514 */
   addRelation(
@@ -179,7 +259,17 @@ export interface TransactionAccessor {
    * @task T10508
    */
   insertAcRows(
-    rows: Array<{ id: string; taskId: string; ordinal: number; text: string }>,
+    rows: Array<{
+      id: string;
+      taskId: string;
+      ordinal: number;
+      text: string;
+      kind?: 'text' | 'child_task' | 'evidence_bound';
+      sourceKey?: string;
+      targetTaskId?: string | null;
+      projection?: string;
+      contentHash?: string | null;
+    }>,
   ): Promise<void>;
   /**
    * Read all AC rows for a task, ordered by ordinal ASC.
@@ -268,6 +358,9 @@ export interface DataAccessor {
   /** Append an entry to the audit log. */
   appendLog(entry: Record<string, unknown>): Promise<void>;
 
+  /** Query recent task audit rows by task id/action, newest first. @task T10594 */
+  queryAuditLog(query: TaskAuditLogQuery): Promise<TaskAuditLogRow[]>;
+
   // ---- Lifecycle ----
 
   /** Release any resources (close DB connections, etc.). */

package/src/dispatch/__tests__/docs-update-registry.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { DOCS_LIFECYCLE_STATUSES } from '../../operations/docs.js';
+import { OPERATIONS } from '../operations-registry.js';
+
+describe('docs.update registry flags (T10617)', () => {
+  it('exposes registry-driven dry-run and strict preflight CLI params', () => {
+    const updateOp = OPERATIONS.find(
+      (op) => op.domain === 'docs' && op.operation === 'update' && op.gateway === 'mutate',
+    );
+
+    expect(updateOp).toBeDefined();
+    const dryRun = updateOp?.params?.find((param) => param.name === 'dryRun');
+    const strict = updateOp?.params?.find((param) => param.name === 'strict');
+
+    expect(dryRun).toMatchObject({
+      type: 'boolean',
+      required: false,
+      cli: { flag: 'dry-run' },
+    });
+    expect(strict).toMatchObject({
+      type: 'boolean',
+      required: false,
+    });
+  });
+
+  it('derives lifecycle help and enum from the runtime docs.update status SSoT', () => {
+    const updateOp = OPERATIONS.find(
+      (op) => op.domain === 'docs' && op.operation === 'update' && op.gateway === 'mutate',
+    );
+    const status = updateOp?.params?.find((param) => param.name === 'status');
+
+    expect(status?.enum).toEqual(DOCS_LIFECYCLE_STATUSES);
+    expect(status?.description).toContain(`Valid: ${DOCS_LIFECYCLE_STATUSES.join('|')}.`);
+  });
+});

package/src/dispatch/__tests__/operation-envelope-snapshots.test.ts

@@ -0,0 +1,283 @@
+import { describe, expect, it } from 'vitest';
+import type { OperationDef } from '../operation-def.js';
+import { OPERATIONS } from '../operations-registry.js';
+
+function opId(op: OperationDef): string {
+  return `${op.gateway}:${op.domain}:${op.operation}`;
+}
+
+function envelopeSnapshot(op: OperationDef | undefined) {
+  expect(op).toBeDefined();
+  return {
+    gateway: op?.gateway,
+    domain: op?.domain,
+    operation: op?.operation,
+    tier: op?.tier,
+    idempotent: op?.idempotent,
+    sessionRequired: op?.sessionRequired,
+    requiredParams: op?.requiredParams ?? [],
+    params: (op?.params ?? []).map((param) => ({
+      name: param.name,
+      type: param.type,
+      required: param.required,
+      cli: param.cli,
+    })),
+  };
+}
+
+function getOp(
+  gateway: OperationDef['gateway'],
+  domain: string,
+  operation: string,
+): OperationDef | undefined {
+  return OPERATIONS.find(
+    (op) => op.gateway === gateway && op.domain === domain && op.operation === operation,
+  );
+}
+
+describe('operation envelope registry snapshots (T10615)', () => {
+  it('keeps high-risk operation identities unique across gateway/domain/operation', () => {
+    const criticalIds = [
+      'query:tasks:show',
+      'query:tasks:workgraph.audit',
+      'mutate:tasks:saga.create',
+      'mutate:docs:update',
+    ];
+    const seen = new Set(OPERATIONS.map(opId));
+
+    expect([...seen].filter((id) => criticalIds.includes(id)).sort()).toEqual(
+      [...criticalIds].sort(),
+    );
+  });
+
+  it('keeps requiredParams aligned with declared params for high-risk envelopes', () => {
+    const criticalOps = [
+      getOp('query', 'tasks', 'show'),
+      getOp('query', 'tasks', 'workgraph.audit'),
+      getOp('mutate', 'tasks', 'saga.create'),
+      getOp('mutate', 'docs', 'update'),
+    ].filter((op): op is OperationDef => op !== undefined);
+
+    const offenders = criticalOps.flatMap((op) => {
+      const paramNames = new Set((op.params ?? []).map((param) => param.name));
+      return (op.requiredParams ?? [])
+        .filter((name) => !paramNames.has(name))
+        .map((missing) => `${opId(op)} missing declared param ${missing}`);
+    });
+
+    expect(offenders).toEqual([]);
+  });
+
+  it('snapshots high-risk operation envelopes consumed by CLI/domain dispatch adapters', () => {
+    const snapshots = {
+      'query:tasks:show': envelopeSnapshot(getOp('query', 'tasks', 'show')),
+      'query:tasks:workgraph.audit': envelopeSnapshot(getOp('query', 'tasks', 'workgraph.audit')),
+      'mutate:tasks:saga.create': envelopeSnapshot(getOp('mutate', 'tasks', 'saga.create')),
+      'mutate:docs:update': envelopeSnapshot(getOp('mutate', 'docs', 'update')),
+    };
+
+    expect(snapshots).toMatchInlineSnapshot(`
+      {
+        "mutate:docs:update": {
+          "domain": "docs",
+          "gateway": "mutate",
+          "idempotent": false,
+          "operation": "update",
+          "params": [
+            {
+              "cli": {
+                "positional": true,
+              },
+              "name": "slug",
+              "required": true,
+              "type": "string",
+            },
+            {
+              "cli": undefined,
+              "name": "file",
+              "required": false,
+              "type": "string",
+            },
+            {
+              "cli": {
+                "flag": "allow-external",
+              },
+              "name": "allowExternal",
+              "required": false,
+              "type": "boolean",
+            },
+            {
+              "cli": undefined,
+              "name": "content",
+              "required": false,
+              "type": "string",
+            },
+            {
+              "cli": undefined,
+              "name": "message",
+              "required": false,
+              "type": "string",
+            },
+            {
+              "cli": undefined,
+              "name": "status",
+              "required": false,
+              "type": "string",
+            },
+            {
+              "cli": {
+                "flag": "dry-run",
+              },
+              "name": "dryRun",
+              "required": false,
+              "type": "boolean",
+            },
+            {
+              "cli": undefined,
+              "name": "strict",
+              "required": false,
+              "type": "boolean",
+            },
+            {
+              "cli": {
+                "flag": "attached-by",
+              },
+              "name": "attachedBy",
+              "required": false,
+              "type": "string",
+            },
+          ],
+          "requiredParams": [
+            "slug",
+          ],
+          "sessionRequired": false,
+          "tier": 1,
+        },
+        "mutate:tasks:saga.create": {
+          "domain": "tasks",
+          "gateway": "mutate",
+          "idempotent": false,
+          "operation": "saga.create",
+          "params": [
+            {
+              "cli": {
+                "flag": "title",
+              },
+              "name": "title",
+              "required": true,
+              "type": "string",
+            },
+            {
+              "cli": {
+                "flag": "description",
+                "short": "-d",
+              },
+              "name": "description",
+              "required": false,
+              "type": "string",
+            },
+            {
+              "cli": {
+                "flag": "acceptance",
+              },
+              "name": "acceptance",
+              "required": false,
+              "type": "array",
+            },
+            {
+              "cli": {
+                "flag": "dry-run",
+              },
+              "name": "dryRun",
+              "required": false,
+              "type": "boolean",
+            },
+          ],
+          "requiredParams": [
+            "title",
+          ],
+          "sessionRequired": false,
+          "tier": 0,
+        },
+        "query:tasks:show": {
+          "domain": "tasks",
+          "gateway": "query",
+          "idempotent": true,
+          "operation": "show",
+          "params": [
+            {
+              "cli": {
+                "positional": true,
+              },
+              "name": "taskId",
+              "required": true,
+              "type": "string",
+            },
+            {
+              "cli": undefined,
+              "name": "history",
+              "required": false,
+              "type": "boolean",
+            },
+            {
+              "cli": undefined,
+              "name": "ivtr-history",
+              "required": false,
+              "type": "boolean",
+            },
+          ],
+          "requiredParams": [
+            "taskId",
+          ],
+          "sessionRequired": false,
+          "tier": 0,
+        },
+        "query:tasks:workgraph.audit": {
+          "domain": "tasks",
+          "gateway": "query",
+          "idempotent": true,
+          "operation": "workgraph.audit",
+          "params": [
+            {
+              "cli": {
+                "positional": true,
+              },
+              "name": "rootId",
+              "required": true,
+              "type": "string",
+            },
+            {
+              "cli": undefined,
+              "name": "maxDepth",
+              "required": false,
+              "type": "number",
+            },
+            {
+              "cli": undefined,
+              "name": "includeRelations",
+              "required": false,
+              "type": "boolean",
+            },
+            {
+              "cli": undefined,
+              "name": "cursor",
+              "required": false,
+              "type": "string",
+            },
+            {
+              "cli": undefined,
+              "name": "limit",
+              "required": false,
+              "type": "number",
+            },
+          ],
+          "requiredParams": [
+            "rootId",
+          ],
+          "sessionRequired": false,
+          "tier": 1,
+        },
+      }
+    `);
+  });
+});