@cleocode/contracts 2026.5.120 → 2026.5.122

package/src/dispatch/operations-registry.ts

@@ -7629,6 +7629,37 @@ export const OPERATIONS: OperationDef[] = [
     ] satisfies ParamDef[],
   },
 
+  // release query: validate-changelog (T9937 / Saga T9862 — canonical CHANGELOG
+  // header validator that replaces the brittle inline grep step in
+  // .github/workflows/release.yml). Read-only — exposed only under the query
+  // gateway because no DB or filesystem mutation occurs.
+  {
+    gateway: 'query',
+    domain: 'release',
+    operation: 'validate-changelog',
+    description:
+      'release.validate-changelog (query) — validate that CHANGELOG.md contains the canonical `## [VERSION]` header per ADR-028 §2.5. Replaces the brittle inline grep in .github/workflows/release.yml (T9937 / Saga T9862).',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['version'],
+    params: [
+      {
+        name: 'version',
+        type: 'string',
+        required: true,
+        description: 'Release version (accepts v2026.5.94 or 2026.5.94)',
+        cli: { positional: true },
+      },
+      {
+        name: 'changelogPath',
+        type: 'string',
+        required: false,
+        description: 'Override the CHANGELOG file path (default: <projectRoot>/CHANGELOG.md)',
+      },
+    ] satisfies ParamDef[],
+  },
+
   // ---------------------------------------------------------------------------
   // Provenance domain — `cleo provenance` CLI surface (T9528 · Phase 2 of T9493)
   // ---------------------------------------------------------------------------

package/src/evidence-atom-schema.ts

@@ -195,6 +195,117 @@ export const callsiteCoverageAtomSchema = z.object({
     .min(1, 'callsite-coverage atom requires a non-empty relativeSourcePath'),
 });
 
+// ---------------------------------------------------------------------------
+// ADR-079-r2: satisfies atom — cross-task AC binding
+// ---------------------------------------------------------------------------
+
+/**
+ * Strict UUIDv4 regex (lowercase, hyphenated 8-4-4-4-12 with the `4` major
+ * version nibble and `[89ab]` variant nibble) per ADR-079-r2 §2.1 ABNF
+ * (`ac-uuid` production) and RFC 9562 §5.4. Used by the `satisfies:` atom
+ * to validate the target-AC UUID form.
+ *
+ * Validators MUST reject mixed-case to prevent silent dedupe failures — the
+ * canonical column casing is lowercase per ADR-079-r1 §2.1.
+ *
+ * @task T10506
+ * @adr ADR-079-r2 §2.1
+ */
+export const AC_UUID_REGEX =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+/**
+ * Positional-alias regex for `satisfies:` atom target-AC identifiers per
+ * ADR-079-r2 §2.1 ABNF (`ac-alias` production). Format: `AC<1-4 digits>`
+ * (capped at AC9999 — three orders of magnitude above realistic per-task AC
+ * counts).
+ *
+ * @task T10506
+ * @adr ADR-079-r2 §2.1
+ */
+export const AC_ALIAS_REGEX = /^AC[0-9]{1,4}$/;
+
+/**
+ * Task-id regex for `satisfies:` atom target-task identifiers per ADR-079-r2
+ * §2.1 ABNF (`task-id` production). Format: `T<1-7 digits>` (capped at
+ * T9999999 — three orders of magnitude above current CLEO task IDs as of
+ * 2026-05-24).
+ *
+ * @task T10506
+ * @adr ADR-079-r2 §2.1
+ */
+export const SATISFIES_TASK_ID_REGEX = /^T[0-9]{1,7}$/;
+
+/**
+ * Version-pin regex for `satisfies:` atom optional `@<ts>` suffix per
+ * ADR-079-r2 §2.1 ABNF (`version-pin` production). Format: `YYYYMMDDhhmmss`
+ * (ISO-8601-basic timestamp, 14 digits).
+ *
+ * @task T10506
+ * @adr ADR-079-r2 §2.1
+ */
+export const SATISFIES_VERSION_PIN_REGEX = /^[0-9]{14}$/;
+
+/**
+ * `satisfies:<task-id>#<ac-id>[@<version-pin>]` atom — cross-task AC binding
+ * per ADR-079-r2 §2.1 (full grammar) and ADR-079-r1 §2.4 (basic shape).
+ *
+ * Format:
+ *
+ *   - `satisfies:T1234#a1b2c3d4-5e6f-4890-abcd-ef1234567890`   — canonical
+ *     UUID form (preferred for long-lived specs).
+ *   - `satisfies:T1234#AC2`                                    — positional
+ *     alias form (preferred in fresh PRs where the target task's AC list
+ *     is stable).
+ *   - `satisfies:T1234#AC2@20260524223045`                     — alias +
+ *     optional version-pin (Validator emissions where pin-on-mint is
+ *     required by ADR-079-r2 §3.4).
+ *
+ * Exactly ONE of `targetAcId` (UUID form) or `targetAcAlias` (alias form)
+ * is populated per parsed atom. `versionPin` is always optional.
+ *
+ * ## Scope
+ *
+ * This Zod schema covers PARSING ONLY. The runtime validator semantics —
+ * the 5-check accept/reject pipeline (target exists, target not terminal,
+ * AC exists, same-saga scope rule) — ship in T10507 alongside the
+ * `evidence_satisfies_bindings` side-effect table.
+ *
+ * Per ADR-079-r2 §2.2 the maximum atom length is 120 chars; the schema does
+ * NOT enforce length here because the per-field regexes already cap the
+ * surface (`satisfies:` + 8-char T+digits + `#` + 36-char UUID + `@` +
+ * 14-char pin = 78 chars max — well under 120).
+ *
+ * @task T10506
+ * @adr ADR-079-r2 §2.1
+ * @adr ADR-079-r1 §2.4
+ */
+export const satisfiesAtomSchema = z.object({
+  kind: z.literal('satisfies'),
+  /** Target task ID — `T<1-7 digits>` per ADR-079-r2 §2.1. */
+  targetTaskId: z
+    .string()
+    .regex(SATISFIES_TASK_ID_REGEX, 'satisfies atom targetTaskId must match /^T[0-9]{1,7}$/'),
+  /** Lowercase UUIDv4 — populated for the canonical form; undefined for alias form. */
+  targetAcId: z
+    .string()
+    .regex(AC_UUID_REGEX, 'satisfies atom targetAcId must be a lowercase UUIDv4')
+    .optional(),
+  /** Positional alias `AC<1-4 digits>` — populated for alias form; undefined for UUID form. */
+  targetAcAlias: z
+    .string()
+    .regex(AC_ALIAS_REGEX, 'satisfies atom targetAcAlias must match /^AC[0-9]{1,4}$/')
+    .optional(),
+  /** Optional `@<14-digit YYYYMMDDhhmmss>` pin captured at mint time. */
+  versionPin: z
+    .string()
+    .regex(
+      SATISFIES_VERSION_PIN_REGEX,
+      'satisfies atom versionPin must be 14 digits (YYYYMMDDhhmmss)',
+    )
+    .optional(),
+});
+
 // ---------------------------------------------------------------------------
 // Discriminated union
 // ---------------------------------------------------------------------------
@@ -218,6 +329,8 @@ export const callsiteCoverageAtomSchema = z.object({
  *   - `pr`                 — merged-PR retroactive proof (T9764 / T9838)
  *   - `loc-drop`           — engine-migration LOC reduction (T1604)
  *   - `callsite-coverage`  — exported-symbol production callsite (T1605)
+ *   - `satisfies`          — cross-task AC binding (T10506 / ADR-079-r2;
+ *                            validator semantics ship in T10507)
  *
  * @task T10337
  * @adr ADR-051
@@ -233,6 +346,7 @@ export const EvidenceAtomSchema = z.discriminatedUnion('kind', [
   prAtomSchema,
   locDropAtomSchema,
   callsiteCoverageAtomSchema,
+  satisfiesAtomSchema,
 ]);
 
 /**
@@ -332,14 +446,25 @@ export const GATE_EVIDENCE_REQUIREMENTS: Readonly<
  * Result of {@link validateEvidenceForGate}.
  *
  * Success carries no extra payload (the caller already holds the atom list).
- * Failure carries a human-readable message in the legacy
- * `Gate '<gate>' requires evidence: [<combo>] OR [<combo>]` format so error
- * surfaces (E_EVIDENCE_INSUFFICIENT) read identically across the CLI and any
- * client-side validator built on top of this schema.
+ * Failure carries:
+ *   - {@link EvidenceValidationFailure.message} — the legacy single-line
+ *     `Gate '<gate>' requires evidence: [<combo>] OR [<combo>]` format,
+ *     preserved byte-for-byte for backward-compat with surfaces and tests
+ *     that match against it.
+ *   - {@link EvidenceValidationFailure.hint} — a richer, multi-line,
+ *     example-bearing remediation hint suitable for CLI `fix:` surfaces.
+ *     Added by T9949 so `E_EVIDENCE_INSUFFICIENT` errors point clearly at
+ *     the alternative atom the caller needs (e.g. "this gate requires
+ *     real proof — note: alone is not accepted; use commit+files,
+ *     commit+note, or pr instead").
  */
-export type EvidenceValidationResult =
-  | { readonly ok: true }
-  | { readonly ok: false; readonly message: string };
+export interface EvidenceValidationFailure {
+  readonly ok: false;
+  readonly message: string;
+  readonly hint: string;
+}
+
+export type EvidenceValidationResult = { readonly ok: true } | EvidenceValidationFailure;
 
 /**
  * Format the satisfying-combinations spec for a gate as the legacy
@@ -354,6 +479,115 @@ export function formatGateRequirement(gate: VerificationGate): string {
   return requirement.oneOf.map((set) => `[${set.join(' AND ')}]`).join(' OR ');
 }
 
+/**
+ * Example `--evidence` strings for each atom kind. Used by
+ * {@link formatGateRequirementHint} to render copy-pasteable remediation
+ * commands in CLI error surfaces.
+ *
+ * @task T9949
+ */
+const ATOM_EXAMPLES: Readonly<Record<EvidenceAtomKind, string>> = Object.freeze({
+  commit: 'commit:<sha>',
+  files: 'files:path/a.ts,path/b.ts',
+  'test-run': 'test-run:/tmp/vitest-out.json',
+  tool: 'tool:test',
+  url: 'url:https://example.com/docs',
+  note: 'note:<short description>',
+  decision: 'decision:D-arch-001',
+  pr: 'pr:357',
+  'loc-drop': 'loc-drop:<fromLines>:<toLines>',
+  'callsite-coverage': 'callsite-coverage:<symbolName>:<relativeSourcePath>',
+  satisfies: 'satisfies:T1234#AC2',
+});
+
+/**
+ * Render a satisfying atom combination as a copy-pasteable `--evidence`
+ * string fragment, e.g. `['commit', 'files']` → `commit:<sha>;files:path/a.ts,path/b.ts`.
+ *
+ * @internal
+ */
+function renderCombinationAsEvidence(combination: ReadonlyArray<EvidenceAtomKind>): string {
+  return combination.map((kind) => ATOM_EXAMPLES[kind]).join(';');
+}
+
+/**
+ * Produce a multi-line, example-bearing remediation hint for a gate.
+ *
+ * Designed for CLI `fix:` surfaces so `E_EVIDENCE_INSUFFICIENT` errors point
+ * the caller at the specific alternative atom shape they need. The hint lists
+ * every satisfying combination as a copy-pasteable `cleo verify` invocation
+ * plus a note-specific clarification when the gate does NOT accept `note:`
+ * alone.
+ *
+ * The motivating bug (T9949) was that note-only deliverables (decision-only
+ * tasks, deletion-only refactors) hit `E_EVIDENCE_INSUFFICIENT` with the
+ * legacy single-line error and had to consult ADR-051 to figure out which
+ * additional atom kind the gate required. The richer hint inlines the answer.
+ *
+ * @param gate - Verification gate the hint is for.
+ * @returns Multi-line remediation hint suitable for an `engineError({fix:})`
+ *   surface. Always ends in a clarifying sentence about whether `note:` alone
+ *   is accepted for the gate.
+ *
+ * @example
+ * ```ts
+ * formatGateRequirementHint('implemented');
+ * // "Gate 'implemented' requires programmatic evidence. Use ONE of:
+ * //   - cleo verify T#### --gate implemented --evidence 'commit:<sha>;files:path/a.ts,path/b.ts'
+ * //   - cleo verify T#### --gate implemented --evidence 'commit:<sha>;note:<short description>'
+ * //   - cleo verify T#### --gate implemented --evidence 'decision:D-arch-001;files:path/a.ts,path/b.ts'
+ * //   - cleo verify T#### --gate implemented --evidence 'decision:D-arch-001;note:<short description>'
+ * //   - cleo verify T#### --gate implemented --evidence 'pr:357'
+ * // Note: 'note:' alone is NOT accepted for this gate — pair it with 'commit:' or 'decision:'."
+ * ```
+ *
+ * @task T9949
+ * @adr ADR-051 §2.3
+ */
+export function formatGateRequirementHint(gate: VerificationGate): string {
+  const requirement = GATE_EVIDENCE_REQUIREMENTS[gate];
+  if (!requirement) {
+    // Unknown gate — match validateEvidenceForGate's defensive default.
+    return `Gate '${gate}' has no documented evidence requirements.`;
+  }
+
+  const lines: string[] = [
+    `Gate '${gate}' requires programmatic evidence. Use ONE of:`,
+    ...requirement.oneOf.map(
+      (combo) =>
+        `  - cleo verify T#### --gate ${gate} --evidence '${renderCombinationAsEvidence(combo)}'`,
+    ),
+  ];
+
+  // Note-specific clarification — T9949's headline pain point.
+  // The gate accepts note: alone IFF some single-element combination is ['note'].
+  const noteAloneAccepted = requirement.oneOf.some(
+    (combo) => combo.length === 1 && combo[0] === 'note',
+  );
+  if (noteAloneAccepted) {
+    lines.push(`Note: 'note:' alone IS accepted for this gate (waiver-style evidence).`);
+  } else {
+    // Surface every alternative pairing involving note for at-a-glance routing.
+    const notePairings = requirement.oneOf.filter(
+      (combo) => combo.length > 1 && combo.includes('note'),
+    );
+    if (notePairings.length > 0) {
+      const partners = Array.from(
+        new Set(notePairings.flatMap((combo) => combo.filter((k) => k !== 'note'))),
+      ).map((k) => `'${k}:'`);
+      lines.push(
+        `Note: 'note:' alone is NOT accepted for this gate — pair it with ${partners.join(' or ')}.`,
+      );
+    } else {
+      lines.push(
+        `Note: 'note:' is NOT accepted for this gate (even when paired). See ADR-051 for the full grammar.`,
+      );
+    }
+  }
+
+  return lines.join('\n');
+}
+
 /**
  * Check whether a set of parsed atoms satisfies the requirement spec for
  * `gate`.
@@ -401,6 +635,11 @@ export function validateEvidenceForGate(
   return {
     ok: false,
     message: `Gate '${gate}' requires evidence: ${formatGateRequirement(gate)}`,
+    // T9949: rich, example-bearing remediation hint suitable for CLI `fix:`.
+    // Always populated alongside `message` so consumers can choose between
+    // the legacy single-line surface and the multi-line hint without re-
+    // computing the spec.
+    hint: formatGateRequirementHint(gate),
   };
 }
 
@@ -594,6 +833,78 @@ export function parseEvidenceString(raw: string): EvidenceAtom[] {
         atoms.push({ kind: 'callsite-coverage', symbolName, relativeSourcePath });
         break;
       }
+      case 'satisfies': {
+        // ADR-079-r2 §2.1 ABNF:
+        //   satisfies-atom = "satisfies:" task-id "#" ac-id [ "@" version-pin ]
+        // Payload shape: <task-id>#<ac-id>[@<version-pin>]
+        //
+        // PARSING ONLY per T10506 — runtime validator semantics (5-check
+        // accept pipeline + same-saga scope rule) ship in T10507.
+        const hashIdx = payload.indexOf('#');
+        if (hashIdx < 1 || hashIdx === payload.length - 1) {
+          throw new EvidenceParseError(
+            `Malformed satisfies atom: "${chunk}" (expected satisfies:<task-id>#<ac-id>[@<version-pin>])`,
+            'Use format: satisfies:T1234#AC2 or satisfies:T1234#<uuid> e.g. satisfies:T10506#AC1',
+          );
+        }
+        const targetTaskId = payload.slice(0, hashIdx).trim();
+        const acAndPin = payload.slice(hashIdx + 1).trim();
+
+        // task-id must match strict ABNF /^T[0-9]{1,7}$/
+        if (!SATISFIES_TASK_ID_REGEX.test(targetTaskId)) {
+          throw new EvidenceParseError(
+            `satisfies atom targetTaskId "${targetTaskId}" must match /^T[0-9]{1,7}$/ in "${chunk}"`,
+            'Use format: satisfies:T<digits>#<ac-id> e.g. satisfies:T1234#AC2',
+          );
+        }
+
+        // Split optional version-pin (after `@`)
+        const atIdx = acAndPin.indexOf('@');
+        let acIdRaw: string;
+        let versionPin: string | undefined;
+        if (atIdx === -1) {
+          acIdRaw = acAndPin;
+          versionPin = undefined;
+        } else {
+          if (atIdx < 1 || atIdx === acAndPin.length - 1) {
+            throw new EvidenceParseError(
+              `Malformed satisfies atom version-pin in "${chunk}" (expected <ac-id>@<14-digit YYYYMMDDhhmmss>)`,
+              'Use format: satisfies:T1234#AC2@20260524223045',
+            );
+          }
+          acIdRaw = acAndPin.slice(0, atIdx).trim();
+          versionPin = acAndPin.slice(atIdx + 1).trim();
+          if (!SATISFIES_VERSION_PIN_REGEX.test(versionPin)) {
+            throw new EvidenceParseError(
+              `satisfies atom versionPin "${versionPin}" must be 14 digits (YYYYMMDDhhmmss) in "${chunk}"`,
+              'Use format: satisfies:T1234#AC2@<YYYYMMDDhhmmss> e.g. satisfies:T1234#AC2@20260524223045',
+            );
+          }
+        }
+
+        // ac-id is EITHER a strict UUIDv4 OR an AC<digits> alias — exactly one.
+        let targetAcId: string | undefined;
+        let targetAcAlias: string | undefined;
+        if (AC_UUID_REGEX.test(acIdRaw)) {
+          targetAcId = acIdRaw;
+        } else if (AC_ALIAS_REGEX.test(acIdRaw)) {
+          targetAcAlias = acIdRaw;
+        } else {
+          throw new EvidenceParseError(
+            `satisfies atom ac-id "${acIdRaw}" must be either a lowercase UUIDv4 or AC<1-4 digits> in "${chunk}"`,
+            'Use format: satisfies:T1234#AC2 (alias) or satisfies:T1234#<lowercase-uuidv4> (canonical)',
+          );
+        }
+
+        atoms.push({
+          kind: 'satisfies',
+          targetTaskId,
+          ...(targetAcId !== undefined ? { targetAcId } : {}),
+          ...(targetAcAlias !== undefined ? { targetAcAlias } : {}),
+          ...(versionPin !== undefined ? { versionPin } : {}),
+        });
+        break;
+      }
       case 'state': {
         // T9838: explicit-form modifier for the preceding pr: atom.
         // Format: pr:<num>;state:MERGED. The resolver always requires
@@ -619,7 +930,7 @@ export function parseEvidenceString(raw: string): EvidenceAtom[] {
       default:
         throw new EvidenceParseError(
           `Unknown evidence kind: "${kind}" in atom "${chunk}"`,
-          'Valid kinds: commit, files, test-run, tool, url, note, loc-drop, callsite-coverage, decision, pr, state',
+          'Valid kinds: commit, files, test-run, tool, url, note, loc-drop, callsite-coverage, decision, pr, satisfies, state',
         );
     }
   }

package/src/exit-codes.ts

@@ -224,6 +224,29 @@ export enum ExitCode {
    * @task T9230
    */
   LEAD_BYPASS_DETECTED = 107,
+
+  /**
+   * `cleo complete <tid>` was rejected because one or more acceptance criteria
+   * on the task have no `evidence_ac_bindings` rows pointing at them. The
+   * coverage gate is the load-bearing IVTR closure piece — every AC the task
+   * declared MUST be backed by a `direct`, `satisfies`, or `coverage` binding
+   * before completion is allowed.
+   *
+   * `error.details.unsatisfied` carries the list of offending ACs (each row
+   * has `acId`, `alias` (`AC<n>`), and `text`). Recovery options:
+   *   1. Add programmatic evidence that resolves the AC via `cleo verify` so
+   *      a binding row is written.
+   *   2. Pass `--waive-ac "<csv>" --waive-reason "<text>"` on `cleo complete`
+   *      to record an audited waiver (`.cleo/audit/ac-waiver.jsonl`).
+   *   3. Set `CLEO_OWNER_OVERRIDE=1` + `CLEO_OWNER_OVERRIDE_REASON=<text>` for
+   *      a full bypass (logged to `.cleo/audit/force-bypass.jsonl`).
+   *
+   * @codeName E_AC_COVERAGE_INCOMPLETE
+   * @task T10509
+   * @saga T10377 (SG-IVTR-AC-BINDING)
+   * @adr ADR-079-r4
+   */
+  AC_COVERAGE_INCOMPLETE = 108,
 }
 
 // ---------------------------------------------------------------------------
@@ -362,6 +385,25 @@ export const E_INVALID_SEVERITY_VALUE = 'E_INVALID_SEVERITY_VALUE' as const;
  */
 export const E_INVALID_PIPELINE_STAGE = 'E_INVALID_PIPELINE_STAGE' as const;
 
+/**
+ * E_AC_COVERAGE_INCOMPLETE — `cleo complete <tid>` was rejected because at
+ * least one acceptance criterion on the task has no `evidence_ac_bindings`
+ * row. The coverage gate is the load-bearing IVTR closure piece — every AC
+ * the task declared MUST be backed by a binding (`direct`, `satisfies`, or
+ * `coverage`) before completion is allowed.
+ *
+ * `error.details.unsatisfied` carries the offending ACs (each entry has
+ * `acId`, `alias`, and `text`). Recovery options live on the {@link ExitCode.AC_COVERAGE_INCOMPLETE}
+ * JSDoc.
+ *
+ * Maps to {@link ExitCode.AC_COVERAGE_INCOMPLETE} (108) at the CLI boundary.
+ *
+ * @task T10509
+ * @saga T10377 (SG-IVTR-AC-BINDING)
+ * @adr ADR-079-r4
+ */
+export const E_AC_COVERAGE_INCOMPLETE = 'E_AC_COVERAGE_INCOMPLETE' as const;
+
 /** Check if an exit code represents an error (1-99). */
 export function isErrorCode(code: ExitCode): boolean {
   return code >= 1 && code < 100;

package/src/index.ts

@@ -257,6 +257,8 @@ export type {
   DepsRequiredAt,
   EnforcementProfile,
   HierarchyConfig,
+  LeadRollupConfig,
+  LeadRollupMode,
   LifecycleConfig,
   LifecycleEnforcementMode,
   LlmConfig,
@@ -288,6 +290,8 @@ export type {
 export { parseClaudeCodeCredentials } from './credentials.js';
 // === DataAccessor Interface ===
 export type {
+  AcBindingRow,
+  AcRow,
   ArchiveFields,
   ArchiveFile,
   DataAccessor,
@@ -475,10 +479,13 @@ export {
 export type {
   EvidenceAtom as EvidenceAtomInput,
   EvidenceAtomKind,
+  EvidenceValidationFailure,
   EvidenceValidationResult,
   GateEvidenceRequirement,
 } from './evidence-atom-schema.js';
 export {
+  AC_ALIAS_REGEX,
+  AC_UUID_REGEX,
   callsiteCoverageAtomSchema,
   commitAtomSchema,
   decisionAtomSchema,
@@ -486,11 +493,15 @@ export {
   EvidenceParseError,
   filesAtomSchema,
   formatGateRequirement,
+  formatGateRequirementHint,
   GATE_EVIDENCE_REQUIREMENTS,
   locDropAtomSchema,
   noteAtomSchema,
   parseEvidenceString,
   prAtomSchema,
+  SATISFIES_TASK_ID_REGEX,
+  SATISFIES_VERSION_PIN_REGEX,
+  satisfiesAtomSchema,
   testRunAtomSchema,
   toolAtomSchema,
   urlAtomSchema,
@@ -525,6 +536,8 @@ export {
 } from './evidence-record-schema.js';
 // === Exit Codes ===
 export {
+  // T10509 / Saga T10377 — AC-coverage gate at cleo complete (IVTR closure)
+  E_AC_COVERAGE_INCOMPLETE,
   // T10105 / Saga T10099 — fail-loud changeset parse
   E_CHANGESET_YAML_INVALID,
   // SPEC-T9345 release pipeline v2 error code names (T9525)
@@ -1273,6 +1286,7 @@ export type {
   DepGraphIssue,
   DepsTreeEdge,
   DepsTreeNode,
+  TaskShowAcRowEntry,
   TaskShowAttachmentEntry,
   TasksAddBatchEntry,
   TasksAddBatchParams,
@@ -1992,6 +2006,31 @@ export type {
   Transport,
   TransportConnectConfig,
 } from './transport.js';
+// === Validator Role Contracts (T10510 / Saga T10377 SG-IVTR-AC-BINDING) ===
+// Canonical AgentRole enum + per-AC ValidatorFinding + ValidatorAttestation /
+// ValidatorRejection envelopes + ValidatorVerdict discriminated union. Consumed
+// by SDK tools (T10511) and the Max-N runtime (T10512) under Epic T10383
+// E-VALIDATOR-ROLE.
+export type {
+  AgentRole,
+  ValidatorAttestation,
+  ValidatorFinding,
+  ValidatorFindingStatus,
+  ValidatorRejection,
+  ValidatorVerdict,
+} from './validator/index.js';
+export {
+  AGENT_ROLES,
+  isAgentRole,
+  isValidatorAttestation,
+  isValidatorRejection,
+  isValidatorVerdict,
+  VALIDATOR_ID_REGEX,
+  validatorAttestationSchema,
+  validatorFindingSchema,
+  validatorRejectionSchema,
+  validatorVerdictSchema,
+} from './validator/index.js';
 // === WarpChain Types ===
 export type {
   ChainShape,

package/src/operations/tasks.ts

@@ -138,6 +138,32 @@ export interface TasksFindParams {
    * @task T9905
    */
   urgent?: boolean;
+  /**
+   * Filter by label — selects tasks whose `labels` array contains this
+   * value. Composes with other filters via AND.
+   *
+   * Closes GH#393 — gives `cleo find --label <name>` parity with the
+   * positional `cleo labels <name>` surface.
+   *
+   * @task T9904
+   */
+  label?: string;
+  /**
+   * Filter by parent task ID — restricts the result set to tasks whose
+   * `parentId` equals this value. Mirrors the `--parent` axis on
+   * `cleo list`. When the parent task is a Saga (Epic with
+   * `label='saga'`), routing goes through `task_relations.type='groups'`
+   * member IDs instead of the `parentId` column (ADR-073 §1).
+   *
+   * Composes with other filters via AND. Closes T10108 — pre-fix,
+   * `cleo find "" --parent <id>` returned every task in the project
+   * because the empty-string query bypassed all filters via
+   * `fuzzyScore('', '<title>')===80`.
+   *
+   * @task T10108
+   * @saga T9862
+   */
+  parent?: string;
 }
 export type TasksFindResult = MinimalTask[];
 
@@ -211,6 +237,38 @@ export interface TasksShowResult {
    * @task T9966
    */
   attachments: TaskShowAttachmentEntry[];
+  /**
+   * Acceptance-criterion rows hydrated from the `task_acceptance_criteria`
+   * table (T10502). Each entry carries the stable UUID `id`, the
+   * `AC<ordinal>` alias, the ordinal itself, and the canonical AC text.
+   *
+   * Optional — undefined when the task has no rows in the table (e.g.
+   * legacy tasks not yet backfilled by T10505). Consumers should fall
+   * back to `task.acceptance` (the legacy JSON string) in that case.
+   *
+   * @task T10508
+   * @epic T10381
+   */
+  acRows?: TaskShowAcRowEntry[];
+}
+
+/**
+ * One acceptance-criterion entry in {@link TasksShowResult.acRows}.
+ *
+ * Mirrors the `AcDetail` shape from `@cleocode/core/tasks/show.js` but
+ * lives in contracts so dispatch-layer consumers don't depend on core.
+ *
+ * @task T10508
+ */
+export interface TaskShowAcRowEntry {
+  /** UUIDv4 stable identifier, immutable for the AC's lifetime. */
+  id: string;
+  /** Display alias derived from ordinal — `AC1`, `AC2`, etc. */
+  alias: string;
+  /** 1-based ordinal — never reused per task (gaps remain on shrink). */
+  ordinal: number;
+  /** The AC statement text. Structured gates round-trip as JSON. */
+  text: string;
 }
 
 // tasks.tree dispatch params (with optional withBlockers flag — dispatch alias)
@@ -900,6 +958,24 @@ export interface TasksCompleteQueryParams {
   overrideReason?: string;
   /** Reason for acknowledging CRITICAL nexus impact risk (bypasses nexusImpact gate). */
   acknowledgeRisk?: string;
+  /**
+   * Comma-separated AC tokens (UUIDs or `AC<n>` aliases) waived from the
+   * AC-coverage gate (T10509). MUST be paired with {@link waiveReason} —
+   * the gate rejects the call when one is set without the other.
+   *
+   * Waivers are recorded to `.cleo/audit/ac-waiver.jsonl` per ADR-079-r4 §4.
+   *
+   * @task T10509
+   * @saga T10377 (SG-IVTR-AC-BINDING)
+   */
+  waiveAc?: string;
+  /**
+   * Justification text for the {@link waiveAc} waiver. Mandatory whenever
+   * `waiveAc` is non-empty.
+   *
+   * @task T10509
+   */
+  waiveReason?: string;
 }
 /**
  * Result of `tasks.complete` — completion confirmation with unblocked tasks.