@cleocode/contracts 2026.5.121 → 2026.5.122

package/dist/validator/index.js

@@ -0,0 +1,162 @@
+/**
+ * Validator role contracts — types consumed by the SDK tools (T10511) and the
+ * Max-N runtime (T10512) to express the verdict a Validator agent returns
+ * after reviewing a Worker submission against a task's acceptance criteria.
+ *
+ * The Validator is a NEW canonical role in the orchestration hierarchy,
+ * orthogonal to the existing Orchestrator → Lead → Worker triad. A Validator
+ * does NOT execute work and does NOT spawn other agents — it ONLY attests or
+ * rejects work claimed-done by another agent, per-AC.
+ *
+ * Identity triad:
+ *  - `agentId` follows the pattern `validator-<discriminator>` (e.g.
+ *    `validator-prime`, `validator-sec-001`).
+ *  - `role` is `'validator'` (see {@link AgentRole}).
+ *  - `sigilCard` is reused as-is from the existing peer/memory layer when
+ *    the Validator is registered as a CANT-defined persona.
+ *
+ * Design constraints (ADR-055 / D028 boundary rules):
+ *  - Lives in `packages/contracts/` — ZERO runtime dependencies (Zod only).
+ *  - Consumed by `packages/cleo-sdk-tools/` (T10511) and `packages/core/` (T10512).
+ *  - No cross-package relative imports.
+ *
+ * @module validator
+ * @task T10510
+ * @epic T10383 (E-VALIDATOR-ROLE)
+ * @saga T10377 (SG-IVTR-AC-BINDING)
+ */
+import { z } from 'zod';
+/**
+ * Frozen list of canonical {@link AgentRole} values for runtime iteration
+ * (e.g. CLI flag validation, registry seeding).
+ *
+ * @task T10510
+ * @epic T10383
+ */
+export const AGENT_ROLES = ['orchestrator', 'lead', 'worker', 'validator'];
+/**
+ * Type guard for {@link AgentRole}. Returns `true` when `value` is one of the
+ * four canonical role strings.
+ *
+ * @task T10510
+ */
+export function isAgentRole(value) {
+    return typeof value === 'string' && AGENT_ROLES.includes(value);
+}
+// ============================================================================
+// Zod schemas — runtime validation
+// ============================================================================
+/**
+ * Regex validating the canonical Validator agentId pattern
+ * `validator-<discriminator>`. The discriminator is `[a-z0-9][a-z0-9-]*`
+ * (lowercase alphanumeric + hyphens, must start with alphanum).
+ *
+ * Examples that MATCH: `validator-prime`, `validator-sec-001`, `validator-a`.
+ * Examples that DO NOT match: `validator-`, `Validator-prime`, `validator--x`.
+ *
+ * @task T10510
+ */
+export const VALIDATOR_ID_REGEX = /^validator-[a-z0-9][a-z0-9-]*$/;
+/**
+ * Zod schema for {@link ValidatorFinding}. Enforces the AC-id presence,
+ * status enum, non-empty reasoning, and ISO-8601 timestamp shape.
+ *
+ * @task T10510
+ */
+export const validatorFindingSchema = z.object({
+    acId: z.string().min(1, 'acId must be non-empty'),
+    status: z.enum(['pass', 'fail', 'inconclusive']),
+    reasoning: z.string().min(1, 'reasoning must be non-empty'),
+    evidenceRefs: z.array(z.string()).optional(),
+    checkedAt: z.string().min(1, 'checkedAt must be a non-empty ISO-8601 string'),
+});
+/**
+ * Zod schema for {@link ValidatorAttestation}. Enforces:
+ *  - `verdict === 'attest'`
+ *  - `validatorId` matches {@link VALIDATOR_ID_REGEX}
+ *  - `findings` non-empty AND every entry has `status === 'pass'`
+ *  - `schemaVersion === '1'`
+ *
+ * @task T10510
+ */
+export const validatorAttestationSchema = z.object({
+    verdict: z.literal('attest'),
+    taskId: z.string().min(1),
+    validatorId: z
+        .string()
+        .regex(VALIDATOR_ID_REGEX, 'validatorId must match the pattern validator-<discriminator>'),
+    findings: z
+        .array(validatorFindingSchema)
+        .min(1, 'attestation must contain at least one finding')
+        .refine((findings) => findings.every((f) => f.status === 'pass'), 'attestation requires every finding to have status="pass"'),
+    summary: z.string().optional(),
+    attestedAt: z.string().min(1),
+    schemaVersion: z.literal('1'),
+});
+/**
+ * Zod schema for {@link ValidatorRejection}. Enforces:
+ *  - `verdict === 'reject'`
+ *  - `validatorId` matches {@link VALIDATOR_ID_REGEX}
+ *  - `findings` non-empty AND at least one entry has `status !== 'pass'`
+ *  - `summary` non-empty (rejection rationale is mandatory)
+ *  - `schemaVersion === '1'`
+ *
+ * @task T10510
+ */
+export const validatorRejectionSchema = z.object({
+    verdict: z.literal('reject'),
+    taskId: z.string().min(1),
+    validatorId: z
+        .string()
+        .regex(VALIDATOR_ID_REGEX, 'validatorId must match the pattern validator-<discriminator>'),
+    findings: z
+        .array(validatorFindingSchema)
+        .min(1, 'rejection must contain at least one finding')
+        .refine((findings) => findings.some((f) => f.status !== 'pass'), 'rejection requires at least one finding with status "fail" or "inconclusive"'),
+    summary: z.string().min(1, 'rejection summary must be non-empty'),
+    remediationHints: z.array(z.string()).optional(),
+    rejectedAt: z.string().min(1),
+    schemaVersion: z.literal('1'),
+});
+/**
+ * Zod schema for the {@link ValidatorVerdict} discriminated union.
+ * Routes parsing through the `verdict` discriminant.
+ *
+ * @task T10510
+ */
+export const validatorVerdictSchema = z.discriminatedUnion('verdict', [
+    validatorAttestationSchema,
+    validatorRejectionSchema,
+]);
+// ============================================================================
+// Type guards
+// ============================================================================
+/**
+ * Type guard validating that `value` conforms to {@link ValidatorAttestation}.
+ * Internally uses {@link validatorAttestationSchema}.
+ *
+ * @task T10510
+ */
+export function isValidatorAttestation(value) {
+    return validatorAttestationSchema.safeParse(value).success;
+}
+/**
+ * Type guard validating that `value` conforms to {@link ValidatorRejection}.
+ * Internally uses {@link validatorRejectionSchema}.
+ *
+ * @task T10510
+ */
+export function isValidatorRejection(value) {
+    return validatorRejectionSchema.safeParse(value).success;
+}
+/**
+ * Type guard validating that `value` conforms to {@link ValidatorVerdict}
+ * (either an attestation or a rejection). Internally uses
+ * {@link validatorVerdictSchema}.
+ *
+ * @task T10510
+ */
+export function isValidatorVerdict(value) {
+    return validatorVerdictSchema.safeParse(value).success;
+}
+//# sourceMappingURL=index.js.map

package/dist/validator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/validator/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.5.121",
+  "version": "2026.5.122",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",
@@ -138,7 +138,7 @@
   "dependencies": {
     "zod": "^4.3.6",
     "zod-to-json-schema": "^3.25.2",
-    "@cleocode/lafs": "2026.5.121"
+    "@cleocode/lafs": "2026.5.122"
   },
   "scripts": {
     "build": "tsc -b --force && node scripts/copy-assets.mjs && node scripts/emit-schemas.mjs",

package/src/__tests__/satisfies-atom.test.ts

@@ -0,0 +1,363 @@
+/**
+ * Tests for the ADR-079-r2 `satisfies:<task-id>#<ac-id>` evidence atom
+ * grammar (T10506).
+ *
+ * Coverage:
+ *   - Schema-level: per-field regex validation (task-id, ac-uuid, ac-alias,
+ *     version-pin) and discriminated-union acceptance.
+ *   - Parser-level: full {@link parseEvidenceString} round-trips for both
+ *     UUID and alias forms, mixed evidence strings, and the optional
+ *     `@<version-pin>` suffix.
+ *   - Malformed inputs: missing colon, missing hash, missing T-prefix,
+ *     mixed-case UUID, non-UUID non-alias ac-id, malformed version-pin.
+ *
+ * This file covers PARSING ONLY per T10506 acceptance criteria. The 5-check
+ * validator semantics (target exists, target not terminal, AC exists, same-
+ * saga scope rule, alias drift detection) ship in T10507 and are tested
+ * separately in `packages/core/src/tasks/__tests__/satisfies-validator.test.ts`.
+ *
+ * @task T10506
+ * @saga T10377
+ * @adr ADR-079-r2
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  AC_ALIAS_REGEX,
+  AC_UUID_REGEX,
+  EvidenceAtomSchema,
+  EvidenceParseError,
+  parseEvidenceString,
+  SATISFIES_TASK_ID_REGEX,
+  SATISFIES_VERSION_PIN_REGEX,
+  satisfiesAtomSchema,
+} from '../index.js';
+
+// ─── Per-field regex parity (ADR-079-r2 §2.1 ABNF) ────────────────────────
+
+describe('satisfies atom regexes (ADR-079-r2 §2.1)', () => {
+  describe('SATISFIES_TASK_ID_REGEX', () => {
+    it('accepts T<1-7 digits>', () => {
+      expect(SATISFIES_TASK_ID_REGEX.test('T1')).toBe(true);
+      expect(SATISFIES_TASK_ID_REGEX.test('T1234')).toBe(true);
+      expect(SATISFIES_TASK_ID_REGEX.test('T1234567')).toBe(true);
+    });
+    it('rejects T<8+ digits>', () => {
+      expect(SATISFIES_TASK_ID_REGEX.test('T12345678')).toBe(false);
+    });
+    it('rejects missing T prefix', () => {
+      expect(SATISFIES_TASK_ID_REGEX.test('1234')).toBe(false);
+    });
+    it('rejects lowercase t', () => {
+      expect(SATISFIES_TASK_ID_REGEX.test('t1234')).toBe(false);
+    });
+    it('rejects non-digit suffix', () => {
+      expect(SATISFIES_TASK_ID_REGEX.test('T12a')).toBe(false);
+    });
+  });
+
+  describe('AC_UUID_REGEX', () => {
+    it('accepts strict lowercase UUIDv4', () => {
+      expect(AC_UUID_REGEX.test('a1b2c3d4-5e6f-4890-abcd-ef1234567890')).toBe(true);
+      expect(AC_UUID_REGEX.test('00000000-0000-4000-8000-000000000000')).toBe(true);
+    });
+    it('rejects mixed-case', () => {
+      // Council-mandated strictness (ADR-079-r2 §2.2): "Validators MUST
+      // reject mixed-case to prevent silent dedupe failures."
+      expect(AC_UUID_REGEX.test('A1B2C3D4-5E6F-4890-ABCD-EF1234567890')).toBe(false);
+    });
+    it('rejects wrong version nibble (not 4)', () => {
+      expect(AC_UUID_REGEX.test('a1b2c3d4-5e6f-5890-abcd-ef1234567890')).toBe(false);
+    });
+    it('rejects wrong variant nibble (not 8/9/a/b)', () => {
+      expect(AC_UUID_REGEX.test('a1b2c3d4-5e6f-4890-cbcd-ef1234567890')).toBe(false);
+    });
+    it('rejects non-UUID strings', () => {
+      expect(AC_UUID_REGEX.test('not-a-uuid')).toBe(false);
+      expect(AC_UUID_REGEX.test('a1b2c3d45e6f4890abcdef1234567890')).toBe(false);
+    });
+  });
+
+  describe('AC_ALIAS_REGEX', () => {
+    it('accepts AC<1-4 digits>', () => {
+      expect(AC_ALIAS_REGEX.test('AC1')).toBe(true);
+      expect(AC_ALIAS_REGEX.test('AC9999')).toBe(true);
+    });
+    it('rejects AC<5+ digits>', () => {
+      expect(AC_ALIAS_REGEX.test('AC10000')).toBe(false);
+    });
+    it('rejects lowercase ac', () => {
+      expect(AC_ALIAS_REGEX.test('ac1')).toBe(false);
+    });
+    it('rejects bare integer', () => {
+      expect(AC_ALIAS_REGEX.test('1')).toBe(false);
+    });
+  });
+
+  describe('SATISFIES_VERSION_PIN_REGEX', () => {
+    it('accepts exactly 14 digits', () => {
+      expect(SATISFIES_VERSION_PIN_REGEX.test('20260524223045')).toBe(true);
+    });
+    it('rejects fewer than 14 digits', () => {
+      expect(SATISFIES_VERSION_PIN_REGEX.test('2026052422304')).toBe(false);
+    });
+    it('rejects more than 14 digits', () => {
+      expect(SATISFIES_VERSION_PIN_REGEX.test('202605242230451')).toBe(false);
+    });
+    it('rejects non-digit characters', () => {
+      expect(SATISFIES_VERSION_PIN_REGEX.test('2026-05-24T22:30')).toBe(false);
+    });
+  });
+});
+
+// ─── Zod schema (post-parse client-side validation) ────────────────────────
+
+describe('satisfiesAtomSchema (ADR-079-r2 §5.2)', () => {
+  it('accepts UUID form without version-pin', () => {
+    const a = satisfiesAtomSchema.parse({
+      kind: 'satisfies',
+      targetTaskId: 'T10495',
+      targetAcId: '8f4a2c1e-b09d-4f6a-9c3e-7a1d4f8c0b2e',
+    });
+    expect(a.targetTaskId).toBe('T10495');
+    expect(a.targetAcId).toBe('8f4a2c1e-b09d-4f6a-9c3e-7a1d4f8c0b2e');
+    expect(a.targetAcAlias).toBeUndefined();
+    expect(a.versionPin).toBeUndefined();
+  });
+
+  it('accepts alias form without version-pin', () => {
+    const a = satisfiesAtomSchema.parse({
+      kind: 'satisfies',
+      targetTaskId: 'T10495',
+      targetAcAlias: 'AC2',
+    });
+    expect(a.targetAcAlias).toBe('AC2');
+    expect(a.targetAcId).toBeUndefined();
+  });
+
+  it('accepts alias form with version-pin', () => {
+    const a = satisfiesAtomSchema.parse({
+      kind: 'satisfies',
+      targetTaskId: 'T10495',
+      targetAcAlias: 'AC2',
+      versionPin: '20260524223045',
+    });
+    expect(a.versionPin).toBe('20260524223045');
+  });
+
+  it('accepts UUID form with version-pin (highest-trust)', () => {
+    const a = satisfiesAtomSchema.parse({
+      kind: 'satisfies',
+      targetTaskId: 'T10495',
+      targetAcId: '8f4a2c1e-b09d-4f6a-9c3e-7a1d4f8c0b2e',
+      versionPin: '20260524223045',
+    });
+    expect(a.targetAcId).toBeDefined();
+    expect(a.versionPin).toBe('20260524223045');
+  });
+
+  it('rejects malformed targetTaskId via schema', () => {
+    const r = satisfiesAtomSchema.safeParse({
+      kind: 'satisfies',
+      targetTaskId: 'task-1234',
+      targetAcAlias: 'AC2',
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects mixed-case UUID via schema', () => {
+    const r = satisfiesAtomSchema.safeParse({
+      kind: 'satisfies',
+      targetTaskId: 'T10495',
+      targetAcId: '8F4A2C1E-B09D-4F6A-9C3E-7A1D4F8C0B2E',
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects malformed version-pin via schema', () => {
+    const r = satisfiesAtomSchema.safeParse({
+      kind: 'satisfies',
+      targetTaskId: 'T10495',
+      targetAcAlias: 'AC2',
+      versionPin: '2026-05-24T22:30',
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('round-trips through the EvidenceAtomSchema discriminated union', () => {
+    const a = EvidenceAtomSchema.parse({
+      kind: 'satisfies',
+      targetTaskId: 'T10495',
+      targetAcAlias: 'AC2',
+    });
+    expect(a.kind).toBe('satisfies');
+  });
+});
+
+// ─── parseEvidenceString (CLI parser) ──────────────────────────────────────
+
+describe('parseEvidenceString — satisfies atom (T10506)', () => {
+  // ─── Valid forms ─────────────────────────────────────────────────────────
+
+  it('parses UUID form', () => {
+    const atoms = parseEvidenceString('satisfies:T10495#8f4a2c1e-b09d-4f6a-9c3e-7a1d4f8c0b2e');
+    expect(atoms).toHaveLength(1);
+    expect(atoms[0]).toEqual({
+      kind: 'satisfies',
+      targetTaskId: 'T10495',
+      targetAcId: '8f4a2c1e-b09d-4f6a-9c3e-7a1d4f8c0b2e',
+    });
+  });
+
+  it('parses alias form', () => {
+    const atoms = parseEvidenceString('satisfies:T10495#AC2');
+    expect(atoms).toHaveLength(1);
+    expect(atoms[0]).toEqual({
+      kind: 'satisfies',
+      targetTaskId: 'T10495',
+      targetAcAlias: 'AC2',
+    });
+  });
+
+  it('parses alias form with version-pin', () => {
+    const atoms = parseEvidenceString('satisfies:T10495#AC2@20260524223045');
+    expect(atoms).toHaveLength(1);
+    expect(atoms[0]).toEqual({
+      kind: 'satisfies',
+      targetTaskId: 'T10495',
+      targetAcAlias: 'AC2',
+      versionPin: '20260524223045',
+    });
+  });
+
+  it('parses UUID form with version-pin (canonical highest-trust)', () => {
+    const atoms = parseEvidenceString(
+      'satisfies:T10495#8f4a2c1e-b09d-4f6a-9c3e-7a1d4f8c0b2e@20260524223045',
+    );
+    expect(atoms).toHaveLength(1);
+    expect(atoms[0]).toEqual({
+      kind: 'satisfies',
+      targetTaskId: 'T10495',
+      targetAcId: '8f4a2c1e-b09d-4f6a-9c3e-7a1d4f8c0b2e',
+      versionPin: '20260524223045',
+    });
+  });
+
+  it('parses multiple satisfies atoms in one evidence string', () => {
+    const atoms = parseEvidenceString('satisfies:T10495#AC2;satisfies:T10493#AC1');
+    expect(atoms).toHaveLength(2);
+    expect(atoms[0]).toMatchObject({
+      kind: 'satisfies',
+      targetTaskId: 'T10495',
+      targetAcAlias: 'AC2',
+    });
+    expect(atoms[1]).toMatchObject({
+      kind: 'satisfies',
+      targetTaskId: 'T10493',
+      targetAcAlias: 'AC1',
+    });
+  });
+
+  it('parses mixed evidence: commit + files + satisfies', () => {
+    const atoms = parseEvidenceString(
+      'commit:abc1234;files:src/foo.ts,src/bar.ts;satisfies:T10495#AC2',
+    );
+    expect(atoms).toHaveLength(3);
+    expect(atoms[0]).toEqual({ kind: 'commit', sha: 'abc1234' });
+    expect(atoms[1]).toEqual({ kind: 'files', paths: ['src/foo.ts', 'src/bar.ts'] });
+    expect(atoms[2]).toEqual({
+      kind: 'satisfies',
+      targetTaskId: 'T10495',
+      targetAcAlias: 'AC2',
+    });
+  });
+
+  it('parses mixed evidence: satisfies + pr (single PR landing multiple ACs)', () => {
+    const atoms = parseEvidenceString('satisfies:T10506#AC1;satisfies:T10506#AC2;pr:773');
+    expect(atoms).toHaveLength(3);
+    expect(atoms[2]).toEqual({ kind: 'pr', prNumber: 773 });
+  });
+
+  // ─── Malformed: missing colon ────────────────────────────────────────────
+
+  it('rejects atom missing the kind-payload colon', () => {
+    // "satisfiesT10495#AC2" — no `:` separator at all
+    expect(() => parseEvidenceString('satisfiesT10495#AC2')).toThrow(EvidenceParseError);
+  });
+
+  // ─── Malformed: missing hash ─────────────────────────────────────────────
+
+  it('rejects atom missing the # separator between task-id and ac-id', () => {
+    expect(() => parseEvidenceString('satisfies:T10495-AC2')).toThrow(EvidenceParseError);
+    expect(() => parseEvidenceString('satisfies:T10495AC2')).toThrow(EvidenceParseError);
+  });
+
+  it('rejects atom with # at start of payload (empty task-id)', () => {
+    expect(() => parseEvidenceString('satisfies:#AC2')).toThrow(EvidenceParseError);
+  });
+
+  it('rejects atom with # at end of payload (empty ac-id)', () => {
+    expect(() => parseEvidenceString('satisfies:T10495#')).toThrow(EvidenceParseError);
+  });
+
+  // ─── Malformed: missing T-prefix on task-id ──────────────────────────────
+
+  it('rejects atom with non-T-prefixed task-id', () => {
+    expect(() => parseEvidenceString('satisfies:10495#AC2')).toThrow(EvidenceParseError);
+    expect(() => parseEvidenceString('satisfies:task-10495#AC2')).toThrow(EvidenceParseError);
+  });
+
+  it('rejects atom with lowercase t prefix', () => {
+    expect(() => parseEvidenceString('satisfies:t10495#AC2')).toThrow(EvidenceParseError);
+  });
+
+  it('rejects atom with task-id exceeding 7 digits', () => {
+    expect(() => parseEvidenceString('satisfies:T12345678#AC2')).toThrow(EvidenceParseError);
+  });
+
+  // ─── Malformed: ac-id ────────────────────────────────────────────────────
+
+  it('rejects atom with mixed-case UUID', () => {
+    // Council §2.2 strictness — silent dedupe prevention
+    expect(() =>
+      parseEvidenceString('satisfies:T10495#8F4A2C1E-B09D-4F6A-9C3E-7A1D4F8C0B2E'),
+    ).toThrow(EvidenceParseError);
+  });
+
+  it('rejects atom with ac-id that is neither UUID nor AC<digits> alias', () => {
+    expect(() => parseEvidenceString('satisfies:T10495#hello')).toThrow(EvidenceParseError);
+    expect(() => parseEvidenceString('satisfies:T10495#2')).toThrow(EvidenceParseError);
+  });
+
+  it('rejects atom with alias exceeding 4 digits', () => {
+    expect(() => parseEvidenceString('satisfies:T10495#AC10000')).toThrow(EvidenceParseError);
+  });
+
+  // ─── Malformed: version-pin ──────────────────────────────────────────────
+
+  it('rejects atom with malformed version-pin (not 14 digits)', () => {
+    expect(() => parseEvidenceString('satisfies:T10495#AC2@2026-05-24')).toThrow(
+      EvidenceParseError,
+    );
+    expect(() => parseEvidenceString('satisfies:T10495#AC2@2026052422304')).toThrow(
+      EvidenceParseError,
+    );
+  });
+
+  it('rejects atom with @ but empty version-pin payload', () => {
+    expect(() => parseEvidenceString('satisfies:T10495#AC2@')).toThrow(EvidenceParseError);
+  });
+
+  // ─── Error message smoke: ensures kind name appears in default-case ──────
+
+  it('includes "satisfies" in the unknown-kind error suggestion list', () => {
+    try {
+      parseEvidenceString('unknownkind:foo');
+      throw new Error('expected EvidenceParseError');
+    } catch (err) {
+      expect(err).toBeInstanceOf(EvidenceParseError);
+      expect((err as EvidenceParseError).fix).toContain('satisfies');
+    }
+  });
+});