@cleocode/contracts 2026.4.69 → 2026.4.72

package/src/index.ts

@@ -6,6 +6,45 @@
  * Implementation packages (@cleocode/core, @cleocode/cleo) import from here.
  */
 
+// === Acceptance Gate Types (machine-verifiable criteria) ===
+export type {
+  AcceptanceGate,
+  AcceptanceGateKind,
+  AcceptanceGateResult,
+  CommandGate,
+  FileAssertion,
+  FileGate,
+  GateBase,
+  GateResultDetails,
+  HttpGate,
+  LintGate,
+  ManualGate,
+  TestGate,
+} from './acceptance-gate.js';
+export type {
+  AcceptanceArrayInput,
+  AcceptanceGateResultInput,
+  AcceptanceGateSchemaInput,
+  AcceptanceItemInput,
+  FileAssertionInput,
+  GateResultDetailsInput,
+} from './acceptance-gate-schema.js';
+// === Acceptance Gate Zod Schemas (runtime validation) ===
+export {
+  acceptanceArraySchema,
+  acceptanceGateResultSchema,
+  acceptanceGateSchema,
+  acceptanceItemSchema,
+  commandGateSchema,
+  fileAssertionSchema,
+  fileGateSchema,
+  gateBaseSchema,
+  gateResultDetailsSchema,
+  httpGateSchema,
+  lintGateSchema,
+  manualGateSchema,
+  testGateSchema,
+} from './acceptance-gate-schema.js';
 // === Provider Adapter Contracts ===
 export type { AdapterHealthStatus, CLEOProviderAdapter } from './adapter.js';
 // === Agent Registry (credential management) ===
@@ -34,6 +73,34 @@ export type {
   CycleTimeDistribution,
   CycleTimePercentiles,
 } from './archive.js';
+// === Attachment Types ===
+export type {
+  Attachment,
+  AttachmentKind,
+  AttachmentMetadata,
+  AttachmentRef,
+  BlobAttachment,
+  LlmsTxtAttachment,
+  LlmtxtDocAttachment,
+  LocalFileAttachment,
+  UrlAttachment,
+} from './attachment.js';
+// === Attachment Zod Schemas (runtime validation) ===
+export type {
+  AttachmentMetadataSchemaInput,
+  AttachmentRefSchemaInput,
+  AttachmentSchemaInput,
+} from './attachment-schema.js';
+export {
+  attachmentMetadataSchema,
+  attachmentRefSchema,
+  attachmentSchema,
+  blobAttachmentSchema,
+  llmsTxtAttachmentSchema,
+  llmtxtDocAttachmentSchema,
+  localFileAttachmentSchema,
+  urlAttachmentSchema,
+} from './attachment-schema.js';
 // === Backup Manifest Types ===
 export type {
   BackupDatabaseEntry,
@@ -134,6 +201,33 @@ export {
   isErrorType,
   normalizeError,
 } from './errors.js';
+// === Evidence Record Types (IVTR typed proof artifacts) ===
+export type {
+  CommandOutputRecord,
+  EvidenceRecord,
+  EvidenceRecordKind,
+  ImplDiffRecord,
+  LintReportRecord,
+  TestOutputRecord,
+  ValidateSpecCheckRecord,
+} from './evidence-record.js';
+export type {
+  CommandOutputRecordInput,
+  EvidenceRecordInput,
+  ImplDiffRecordInput,
+  LintReportRecordInput,
+  TestOutputRecordInput,
+  ValidateSpecCheckRecordInput,
+} from './evidence-record-schema.js';
+// === Evidence Record Zod Schemas (runtime validation) ===
+export {
+  commandOutputRecordSchema,
+  evidenceRecordSchema,
+  implDiffRecordSchema,
+  lintReportRecordSchema,
+  testOutputRecordSchema,
+  validateSpecCheckRecordSchema,
+} from './evidence-record-schema.js';
 // === Exit Codes ===
 export {
   ExitCode,
@@ -323,6 +417,7 @@ export {
 } from './status-registry.js';
 // === Task Types ===
 export type {
+  AcceptanceItem,
   CancelledTask,
   CompletedTask,
   EpicLifecycle,
@@ -348,6 +443,25 @@ export type {
   VerificationFailure,
   VerificationGate,
 } from './task.js';
+// === Task Evidence Types (T801) ===
+export type {
+  CommandOutputEvidence,
+  FileEvidence,
+  LogEvidence,
+  ScreenshotEvidence,
+  TaskEvidence,
+  TaskEvidenceInput,
+  TaskEvidenceKind,
+  TestOutputEvidence,
+} from './task-evidence.js';
+export {
+  commandOutputEvidenceSchema,
+  fileEvidenceSchema,
+  logEvidenceSchema,
+  screenshotEvidenceSchema,
+  taskEvidenceSchema,
+  testOutputEvidenceSchema,
+} from './task-evidence.js';
 // === TaskRecord Types (string-widened for dispatch/LAFS) ===
 export type {
   MinimalTaskRecord,
@@ -396,5 +510,4 @@ export type {
   WarpLink,
   WarpStage,
 } from './warp-chain.js';
-
 // === WASM SDK (Rust crate bindings) ===

package/src/task-evidence.ts

@@ -0,0 +1,239 @@
+/**
+ * TaskEvidence discriminated union — typed evidence references for verification records.
+ *
+ * Replaces free-text evidence fields in verification records with structured,
+ * kind-specific evidence artifacts. Each variant carries a SHA-256 attachment
+ * reference, a timestamp, and optional description.
+ *
+ * Five evidence kinds are supported:
+ * - `file`           — a file artifact (source file, output artifact, config)
+ * - `log`            — a log stream captured from a process
+ * - `screenshot`     — a visual capture (PNG/JPEG/WEBP)
+ * - `test-output`    — structured test-runner output
+ * - `command-output` — raw stdout/stderr from a shell command
+ *
+ * @epic T760
+ * @task T801
+ * @see {@link AcceptanceGateResult} — `evidence` field
+ */
+
+import { z } from 'zod';
+
+// ─── Variant interfaces ───────────────────────────────────────────────────────
+
+/**
+ * Evidence for a file artifact produced or inspected during verification.
+ *
+ * The `sha256` is the content hash of the file at capture time, used to
+ * look up the blob in the attachment store.
+ */
+export interface FileEvidence {
+  kind: 'file';
+  /** SHA-256 hex digest of the file at capture time (attachment ref). */
+  sha256: string;
+  /** ISO 8601 timestamp when evidence was captured. */
+  timestamp: string;
+  /** Path to the file, relative to the project root. */
+  path: string;
+  /** IANA MIME type of the file (e.g. `"text/typescript"`, `"application/pdf"`). */
+  mime?: string;
+  /** Optional human-readable note about this evidence artifact. */
+  description?: string;
+}
+
+/**
+ * Evidence for a log stream captured from a running process.
+ *
+ * The `sha256` is the content hash of the captured log text.
+ */
+export interface LogEvidence {
+  kind: 'log';
+  /** SHA-256 hex digest of the captured log content. */
+  sha256: string;
+  /** ISO 8601 timestamp when evidence was captured. */
+  timestamp: string;
+  /**
+   * Source process name or description (e.g. `"pnpm test"`, `"node server.js"`).
+   */
+  source: string;
+  /** Optional human-readable note about this log artifact. */
+  description?: string;
+}
+
+/**
+ * Evidence for a screenshot or visual capture taken during verification.
+ *
+ * Used for manual gates and UI smoke tests. The `sha256` references the
+ * image blob in the attachment store.
+ */
+export interface ScreenshotEvidence {
+  kind: 'screenshot';
+  /** SHA-256 hex digest of the image file. */
+  sha256: string;
+  /** ISO 8601 timestamp when evidence was captured. */
+  timestamp: string;
+  /**
+   * MIME type of the image.
+   *
+   * @defaultValue "image/png"
+   */
+  mime?: 'image/png' | 'image/jpeg' | 'image/webp';
+  /** Optional human-readable note (e.g. `"dark mode toggle on macOS Chrome"`). */
+  description?: string;
+}
+
+/**
+ * Evidence for structured test-runner output.
+ *
+ * Carries the summary metrics from the test run alongside the SHA-256
+ * reference to the full output blob.
+ */
+export interface TestOutputEvidence {
+  kind: 'test-output';
+  /** SHA-256 hex digest of the full test-runner output. */
+  sha256: string;
+  /** ISO 8601 timestamp when evidence was captured. */
+  timestamp: string;
+  /** Number of tests that passed. */
+  passed: number;
+  /** Number of tests that failed. */
+  failed: number;
+  /** Number of tests skipped or pending. */
+  skipped: number;
+  /** Exit code of the test process. */
+  exitCode: number;
+  /** Optional human-readable note about the test run. */
+  description?: string;
+}
+
+/**
+ * Evidence for raw stdout/stderr output from a shell command.
+ *
+ * The `sha256` references the full output blob in the attachment store.
+ */
+export interface CommandOutputEvidence {
+  kind: 'command-output';
+  /** SHA-256 hex digest of the full command output. */
+  sha256: string;
+  /** ISO 8601 timestamp when evidence was captured. */
+  timestamp: string;
+  /** The command that was run (e.g. `"pnpm run build"`). */
+  cmd: string;
+  /** Exit code of the command process. */
+  exitCode: number;
+  /** Optional human-readable note about the command run. */
+  description?: string;
+}
+
+// ─── Discriminated union ──────────────────────────────────────────────────────
+
+/**
+ * A typed evidence artifact attached to a verification record.
+ *
+ * Replaces the bare `evidence?: string` field on {@link AcceptanceGateResult}
+ * with structured, kind-specific references backed by the attachment store.
+ *
+ * The `kind` field is the discriminant. All variants carry `sha256` (the
+ * attachment store ref), `timestamp`, and optional `description`.
+ *
+ * @example
+ * ```ts
+ * const ev: TaskEvidence = {
+ *   kind: 'test-output',
+ *   sha256: 'a1b2c3...ff',
+ *   timestamp: '2026-04-15T10:00:00.000Z',
+ *   passed: 42,
+ *   failed: 0,
+ *   skipped: 2,
+ *   exitCode: 0,
+ * };
+ * ```
+ */
+export type TaskEvidence =
+  | FileEvidence
+  | LogEvidence
+  | ScreenshotEvidence
+  | TestOutputEvidence
+  | CommandOutputEvidence;
+
+/** All valid `kind` discriminants for `TaskEvidence`. */
+export type TaskEvidenceKind = TaskEvidence['kind'];
+
+// ─── Zod schemas ─────────────────────────────────────────────────────────────
+
+/** Zod schema for {@link FileEvidence}. */
+export const fileEvidenceSchema = z.object({
+  kind: z.literal('file'),
+  sha256: z.string().length(64),
+  timestamp: z.string().datetime(),
+  path: z.string().min(1),
+  mime: z.string().optional(),
+  description: z.string().optional(),
+});
+
+/** Zod schema for {@link LogEvidence}. */
+export const logEvidenceSchema = z.object({
+  kind: z.literal('log'),
+  sha256: z.string().length(64),
+  timestamp: z.string().datetime(),
+  source: z.string().min(1),
+  description: z.string().optional(),
+});
+
+/** Zod schema for {@link ScreenshotEvidence}. */
+export const screenshotEvidenceSchema = z.object({
+  kind: z.literal('screenshot'),
+  sha256: z.string().length(64),
+  timestamp: z.string().datetime(),
+  mime: z.enum(['image/png', 'image/jpeg', 'image/webp']).optional(),
+  description: z.string().optional(),
+});
+
+/** Zod schema for {@link TestOutputEvidence}. */
+export const testOutputEvidenceSchema = z.object({
+  kind: z.literal('test-output'),
+  sha256: z.string().length(64),
+  timestamp: z.string().datetime(),
+  passed: z.number().int().nonnegative(),
+  failed: z.number().int().nonnegative(),
+  skipped: z.number().int().nonnegative(),
+  exitCode: z.number().int(),
+  description: z.string().optional(),
+});
+
+/** Zod schema for {@link CommandOutputEvidence}. */
+export const commandOutputEvidenceSchema = z.object({
+  kind: z.literal('command-output'),
+  sha256: z.string().length(64),
+  timestamp: z.string().datetime(),
+  cmd: z.string().min(1),
+  exitCode: z.number().int(),
+  description: z.string().optional(),
+});
+
+/**
+ * Zod discriminated-union schema for {@link TaskEvidence}.
+ *
+ * Uses `z.discriminatedUnion('kind', [...])` for O(1) variant lookup.
+ *
+ * @example
+ * ```ts
+ * const ev = taskEvidenceSchema.parse({
+ *   kind: 'command-output',
+ *   sha256: 'a'.repeat(64),
+ *   timestamp: '2026-04-15T10:00:00.000Z',
+ *   cmd: 'pnpm run build',
+ *   exitCode: 0,
+ * });
+ * ```
+ */
+export const taskEvidenceSchema = z.discriminatedUnion('kind', [
+  fileEvidenceSchema,
+  logEvidenceSchema,
+  screenshotEvidenceSchema,
+  testOutputEvidenceSchema,
+  commandOutputEvidenceSchema,
+]);
+
+/** Inferred TypeScript type from {@link taskEvidenceSchema}. */
+export type TaskEvidenceInput = z.input<typeof taskEvidenceSchema>;

package/src/task.ts

@@ -21,10 +21,23 @@
  * @task T4456
  */
 
+import type { AcceptanceGate } from './acceptance-gate.js';
 import type { TaskStatus } from './status-registry.js';
 
 export type { TaskStatus };
 
+/**
+ * A single acceptance criterion — either a free-text string (legacy) or a
+ * structured {@link AcceptanceGate} (machine-verifiable).
+ *
+ * Mixed arrays of these are stored as JSON in the `acceptance_json` column.
+ *
+ * @epic T760
+ * @task T780
+ * @task T800
+ */
+export type AcceptanceItem = string | AcceptanceGate;
+
 /** Task priority levels. */
 export type TaskPriority = 'critical' | 'high' | 'medium' | 'low';
 
@@ -169,8 +182,15 @@ export interface Task {
   /** File paths associated with this task. @defaultValue undefined */
   files?: string[];
 
-  /** Acceptance criteria for completion. @defaultValue undefined */
-  acceptance?: string[];
+  /**
+   * Mixed acceptance criteria — free-text strings (legacy) and/or structured
+   * {@link AcceptanceGate} objects (machine-verifiable).
+   *
+   * @epic T760
+   * @task T780
+   * @defaultValue undefined
+   */
+  acceptance?: AcceptanceItem[];
 
   /** IDs of tasks this task depends on. @defaultValue undefined */
   depends?: string[];
@@ -296,8 +316,8 @@ export interface TaskCreate {
   /** File paths associated with this task. @defaultValue undefined */
   files?: string[];
 
-  /** Acceptance criteria. @defaultValue undefined */
-  acceptance?: string[];
+  /** Acceptance criteria (string or AcceptanceGate objects). @defaultValue undefined */
+  acceptance?: AcceptanceItem[];
 
   /** IDs of tasks this task depends on. @defaultValue undefined */
   depends?: string[];