@cleocode/contracts 2026.5.121 → 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/config.ts

@@ -530,6 +530,50 @@ export interface DecisionsConfig {
   validatorConfidenceThreshold?: number;
 }
 
+/**
+ * Operating mode for the Lead-tier wave roll-up
+ * (`packages/core/src/orchestration/lead-rollup.ts`).
+ *
+ * - `'passive'` — Default, backward-compatible behaviour. `rollupWaveStatus` /
+ *   `rollupEpicStatus` compute the rollup contract from manifest +
+ *   verification rows only. The Lead reads the result and decides what to do
+ *   externally.
+ * - `'active'`  — Enables the Lead↔Worker Max-N loop scaffolded by T10383
+ *   (E-VALIDATOR-ROLE). The rollup will additionally surface retry-eligible
+ *   workers and emit Lead-initiated retry signals.  The wiring of retries
+ *   themselves lives in T10512 — this flag is the gate.
+ * - `'auto'`    — Reserved for future heuristic selection (e.g. switch to
+ *   active mode iff the epic has ≥N pending workers). Treated as `'passive'`
+ *   at runtime until the heuristic ships.
+ *
+ * @task T10513
+ * @saga T10377
+ * @adr ADR-070
+ */
+export type LeadRollupMode = 'passive' | 'active' | 'auto';
+
+/**
+ * Lead-tier wave roll-up configuration.
+ *
+ * Single-key config block gating the Lead↔Worker Max-N loop introduced by
+ * SG-IVTR-AC-BINDING (T10377) and council action #9 of E-VALIDATOR-ROLE
+ * (T10383). The whole point of this block is to keep the existing
+ * `rollupWaveStatus` / `rollupEpicStatus` function signatures unchanged —
+ * callers pick up new behaviour by flipping the config key, never by
+ * threading a new parameter.
+ *
+ * @task T10513
+ * @saga T10377
+ */
+export interface LeadRollupConfig {
+  /**
+   * Roll-up operating mode. Defaults to `'passive'` for backward compatibility.
+   *
+   * @defaultValue 'passive'
+   */
+  mode?: LeadRollupMode;
+}
+
 /** CLEO project configuration (config.json). */
 export interface CleoConfig {
   /** Configuration schema version string. */
@@ -603,6 +647,20 @@ export interface CleoConfig {
    * @task T9410
    */
   auth?: AuthConfig;
+  /**
+   * Lead-tier wave roll-up configuration.
+   *
+   * Gates the Lead↔Worker Max-N loop scaffolded under SG-IVTR-AC-BINDING
+   * (T10377) and council action #9 of E-VALIDATOR-ROLE (T10383). When
+   * absent, the roll-up defaults to `{ mode: 'passive' }` — the legacy
+   * compute-from-manifest behaviour — so existing callers continue to work
+   * unchanged.
+   *
+   * @defaultValue undefined
+   * @task T10513
+   * @saga T10377
+   */
+  leadRollup?: LeadRollupConfig;
 }
 
 /**

package/src/data-accessor.ts

@@ -107,6 +107,127 @@ export interface TaskFieldUpdates {
   pipelineStage?: string | null;
 }
 
+/**
+ * A row of the `task_acceptance_criteria` table (T10502).
+ *
+ * @task T10508
+ */
+export interface AcRow {
+  /** UUIDv4 stable identifier, immutable for the AC's lifetime. */
+  id: string;
+  /** Owning task ID. */
+  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. */
+  createdAt: string;
+  /** ISO-8601 last-edit timestamp; null until first edit. */
+  updatedAt: string | null;
+  /** Optional sha256(text) snapshot; writers MAY populate, readers MUST treat null as "unknown". */
+  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
+ * (T10509) — "what evidence has been recorded against this AC?".
+ *
+ * @task T10509
+ * @saga T10377 (SG-IVTR-AC-BINDING)
+ */
+export interface AcBindingRow {
+  /** UUIDv4 — set by the writer (T10505/T10506). */
+  id: string;
+  /** Stable hash / composite key of the evidence atom. NOT an FK. */
+  evidenceAtomId: string;
+  /** FK → `task_acceptance_criteria(id)`. */
+  acId: string;
+  /** One of {direct, satisfies, coverage}. */
+  bindingType: 'direct' | 'satisfies' | 'coverage';
+  /** ISO-8601 timestamp of binding creation. */
+  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).
@@ -117,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(
@@ -129,8 +252,80 @@ export interface TransactionAccessor {
   removeRelation(taskId: string, relatedTo: string, relationType?: string): Promise<void>;
   /** Remove all relations for a task (both directions) — used for set-replace. @task T9514 */
   clearRelations(taskId: string): Promise<void>;
+  /**
+   * Insert AC rows into `task_acceptance_criteria` with caller-supplied
+   * UUIDs and ordinals. Ordinals MUST NOT collide with existing rows for
+   * the same task — the UNIQUE (task_id, ordinal) index enforces this.
+   * @task T10508
+   */
+  insertAcRows(
+    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.
+   * Available inside transactions for shrink/replace flows that need to
+   * read the current state before deletion.
+   * @task T10508
+   */
+  getAcRows(taskId: string): Promise<AcRow[]>;
+  /**
+   * Delete all AC rows for a task. Used by update-replace-all + update-shrink
+   * flows AFTER the history rows have been appended.
+   * @task T10508
+   */
+  deleteAcRowsForTask(taskId: string): Promise<void>;
+  /**
+   * Append a history row to `task_acceptance_criteria_history` capturing the
+   * AC text that is about to be superseded.
+   * @task T10508
+   */
+  appendAcHistory(
+    rows: Array<{ acId: string; previousText: string; reason: string }>,
+  ): Promise<void>;
+  /**
+   * Read all `evidence_ac_bindings` rows whose `ac_id` ∈ the given set.
+   * Used by the AC-coverage gate (T10509) to compute which ACs are
+   * satisfied vs unsatisfied inside the same transaction that flips the
+   * task to `done`.
+   *
+   * Returns the empty array when `acIds` is empty.
+   *
+   * @task T10509
+   */
+  getAcBindings(acIds: readonly string[]): Promise<AcBindingRow[]>;
+  /**
+   * Insert rows into `evidence_ac_bindings`. Used by the Validator SDK
+   * tools (T10511) to persist coverage bindings transactionally after a
+   * Validator attestation. The UNIQUE (evidence_atom_id, ac_id, binding_type)
+   * index collapses idempotent re-inserts via `ON CONFLICT DO NOTHING`.
+   *
+   * No-op when `rows` is empty.
+   *
+   * @task T10511
+   * @saga T10377 (SG-IVTR-AC-BINDING)
+   */
+  insertAcBindings(
+    rows: Array<{
+      id: string;
+      evidenceAtomId: string;
+      acId: string;
+      bindingType: 'direct' | 'satisfies' | 'coverage';
+    }>,
+  ): Promise<void>;
 }
 
+// Re-export AcRow at the module level for both transaction + outer accessor use.
+
 /**
  * DataAccessor interface.
  *
@@ -163,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.). */
@@ -193,6 +391,21 @@ export interface DataAccessor {
   /** Remove a row from the task_relations table (T9240). */
   removeRelation(taskId: string, relatedTo: string, relationType?: string): Promise<void>;
 
+  /**
+   * Read AC rows for a task from `task_acceptance_criteria`, ordered by
+   * ordinal ASC. Returns the empty array if no rows exist.
+   * @task T10508
+   */
+  getAcRows(taskId: string): Promise<AcRow[]>;
+
+  /**
+   * Read `evidence_ac_bindings` rows whose `ac_id` ∈ the given set.
+   * Powers the AC-coverage gate (T10509). Returns the empty array when
+   * `acIds` is empty or no bindings exist for the supplied ids.
+   * @task T10509
+   */
+  getAcBindings(acIds: readonly string[]): Promise<AcBindingRow[]>;
+
   // ---- Metadata (schema_meta KV store) ----
 
   /** Read a typed value from the metadata store. Returns null if not found. */

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('|')}.`);
+  });
+});