@cleocode/contracts 2026.5.112 → 2026.5.113

package/src/invariants/index.ts

@@ -11,7 +11,8 @@
  * 5. Render documentation via the downstream R8 auto-render pipeline.
  *
  * Downstream consumers:
- * - R2 (T10336): register ADR-070 ORC codes into this same registry.
+ * - R2 (T10336, SHIPPED): registers ADR-070 ORC-001..ORC-014 codes into
+ *   this same registry via `./adr-070-orchestration.ts`.
  * - R4 (T10338): CI gate validates that every `severity:'error'` entry has
  *   a non-null `runtimeGate` AND a matching error-code in `errors.ts`.
  * - R5 (T10339): refactor `packages/core/src/release/invariants/registry.ts`
@@ -26,10 +27,14 @@
  * @see ADR-073-above-epic-naming.md §1.2
  */
 
+import { ADR_056_INVARIANTS } from './adr-056-release.js';
+import { ADR_070_INVARIANTS } from './adr-070-orchestration.js';
 import { ADR_073_INVARIANTS } from './adr-073-saga.js';
 
 // Re-exported so consumers can import either the per-ADR list or the merged
 // registry from one place.
+export { ADR_056_INVARIANTS } from './adr-056-release.js';
+export { ADR_070_INVARIANTS } from './adr-070-orchestration.js';
 export { ADR_073_INVARIANTS } from './adr-073-saga.js';
 
 /**
@@ -149,7 +154,11 @@ function buildKey(invariant: RegisteredInvariant): string {
  * @internal
  */
 function buildRegistry(): Readonly<Record<string, RegisteredInvariant>> {
-  const entries: RegisteredInvariant[] = [...ADR_073_INVARIANTS];
+  const entries: RegisteredInvariant[] = [
+    ...ADR_073_INVARIANTS,
+    ...ADR_056_INVARIANTS,
+    ...ADR_070_INVARIANTS,
+  ];
   const record: Record<string, RegisteredInvariant> = {};
   for (const entry of entries) {
     const key = buildKey(entry);

package/src/operations/__tests__/input-contract.test.ts

@@ -0,0 +1,188 @@
+/**
+ * Type + construction tests for OperationInputContract, ValidationResult,
+ * and ValidationError.
+ *
+ * These tests are intentionally minimal — the contracts package is a leaf
+ * with zero runtime dependencies, so there is no validator to exercise
+ * here. Instead, we assert:
+ *
+ *   1. ValidationResult narrows correctly via the `ok` discriminator.
+ *   2. A typed OperationInputContract<T> can be constructed and its
+ *      examples[0].value satisfies the generic.
+ *   3. ValidationError can be constructed with all 6 required fields.
+ *
+ * The runtime validator that consumes these types ships under T9915.
+ *
+ * @epic T9855
+ * @task T9914
+ */
+
+import { describe, expect, it } from 'vitest';
+import type {
+  JsonSchema,
+  OperationInputContract,
+  OperationInputContractRegistry,
+  ValidationError,
+  ValidationResult,
+} from '../input-contract.js';
+
+// ---------------------------------------------------------------------------
+// ValidationResult discriminated-union narrowing
+// ---------------------------------------------------------------------------
+
+describe('ValidationResult<T>', () => {
+  it('narrows to the success branch when ok is true', () => {
+    // Constructor return type is widened so TS keeps both branches reachable
+    // at the call site — that's the whole point of the discriminated union.
+    const makeResult = (): ValidationResult<{ title: string }> => ({
+      ok: true,
+      value: { title: 'Ship E7' },
+    });
+    const result = makeResult();
+
+    if (result.ok) {
+      // Type-level: TypeScript narrows result.value to { title: string }.
+      // Runtime: the value is exactly what we constructed.
+      expect(result.value.title).toBe('Ship E7');
+    } else {
+      // Type-level: result.errors is ValidationError[].
+      expect(result.errors).toEqual([]);
+    }
+  });
+
+  it('narrows to the failure branch when ok is false', () => {
+    const makeResult = (): ValidationResult<{ title: string }> => ({
+      ok: false,
+      errors: [
+        {
+          path: '/title',
+          expected: 'string with minLength 1',
+          received: 'empty string',
+          fix: 'Provide a non-empty title.',
+          errorCode: 'E_INPUT_MIN_LENGTH',
+          schemaPath: '#/properties/title/minLength',
+        },
+      ],
+    });
+    const result = makeResult();
+
+    if (result.ok) {
+      expect(result.value).toBeDefined();
+    } else {
+      expect(result.errors).toHaveLength(1);
+      expect(result.errors[0]?.errorCode).toBe('E_INPUT_MIN_LENGTH');
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// OperationInputContract<T> construction
+// ---------------------------------------------------------------------------
+
+describe('OperationInputContract<T>', () => {
+  it('builds a typed contract whose examples match the generic', () => {
+    interface CreateTaskInput {
+      title: string;
+      acceptance: string;
+    }
+
+    const schema: JsonSchema = {
+      type: 'object',
+      required: ['title', 'acceptance'],
+      properties: {
+        title: { type: 'string', minLength: 1, maxLength: 200 },
+        acceptance: { type: 'string', minLength: 1 },
+      },
+      additionalProperties: false,
+    };
+
+    const contract: OperationInputContract<CreateTaskInput> = {
+      operation: 'tasks.create',
+      schema,
+      examples: [
+        {
+          name: 'minimal',
+          value: { title: 'Ship E7', acceptance: 'PR merged' },
+          description: 'Smallest valid payload.',
+        },
+      ],
+    };
+
+    expect(contract.operation).toBe('tasks.create');
+    expect(contract.schema).toBe(schema);
+    expect(contract.examples).toHaveLength(1);
+
+    const first = contract.examples[0];
+    expect(first).toBeDefined();
+    // Type-level: first.value is CreateTaskInput. Runtime sanity:
+    expect(first?.value.title).toBe('Ship E7');
+    expect(first?.value.acceptance).toBe('PR merged');
+    expect(first?.name).toBe('minimal');
+    expect(first?.description).toBe('Smallest valid payload.');
+  });
+
+  it('accepts a contract with an example that omits the optional description', () => {
+    const contract: OperationInputContract<{ id: string }> = {
+      operation: 'docs.fetch',
+      schema: { type: 'object', required: ['id'], properties: { id: { type: 'string' } } },
+      examples: [{ name: 'minimal', value: { id: 'adr-076' } }],
+    };
+
+    expect(contract.examples[0]?.description).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ValidationError shape
+// ---------------------------------------------------------------------------
+
+describe('ValidationError', () => {
+  it('constructs with all 6 required fields', () => {
+    const err: ValidationError = {
+      path: '/owners/0/email',
+      expected: 'string matching email format',
+      received: 'string',
+      fix: 'Use a valid email address (e.g. user@example.com).',
+      errorCode: 'E_INPUT_FORMAT_EMAIL',
+      schemaPath: '#/properties/owners/items/properties/email/format',
+    };
+
+    expect(err.path).toBe('/owners/0/email');
+    expect(err.expected).toBe('string matching email format');
+    expect(err.received).toBe('string');
+    expect(err.fix).toBe('Use a valid email address (e.g. user@example.com).');
+    expect(err.errorCode).toBe('E_INPUT_FORMAT_EMAIL');
+    expect(err.schemaPath).toBe('#/properties/owners/items/properties/email/format');
+
+    // All 6 fields present — no extras.
+    expect(Object.keys(err).sort()).toEqual([
+      'errorCode',
+      'expected',
+      'fix',
+      'path',
+      'received',
+      'schemaPath',
+    ]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Registry shape
+// ---------------------------------------------------------------------------
+
+describe('OperationInputContractRegistry', () => {
+  it('keys contracts by their operation identifier', () => {
+    const createTask: OperationInputContract<{ title: string }> = {
+      operation: 'tasks.create',
+      schema: { type: 'object', required: ['title'], properties: { title: { type: 'string' } } },
+      examples: [{ name: 'minimal', value: { title: 'a' } }],
+    };
+
+    const registry: OperationInputContractRegistry = {
+      'tasks.create': createTask as OperationInputContract<unknown>,
+    };
+
+    expect(registry['tasks.create']?.operation).toBe('tasks.create');
+    expect(registry['unknown.op']).toBeUndefined();
+  });
+});

package/src/operations/docs.ts

@@ -405,6 +405,22 @@ export interface DocsAddParams {
    * @task T9637 (T-DOCS-SLUG-2)
    */
   type?: DocsType;
+  /**
+   * When `true`, body-schema validation against
+   * {@link DocKindMetadata.requiredSections} is enforced — a missing
+   * required H2 section returns `E_DOC_SCHEMA_MISMATCH` with the
+   * missing-sections list in `details.missing`. When omitted or `false`,
+   * the validator runs in advisory mode: the write proceeds and any
+   * missing sections surface as a warning in the envelope's `meta`.
+   *
+   * Only meaningful when `file` is set; URL attachments skip body
+   * validation (no local bytes to scan).
+   *
+   * @task T10160 (E12.C3 · absorbs T10154)
+   * @epic T10157
+   * @saga T9855
+   */
+  strict?: boolean;
 }
 
 /**

package/src/operations/input-contract.ts

@@ -0,0 +1,301 @@
+/**
+ * OperationInputContract — schema-first input contract for CLEO operations.
+ *
+ * This module is the SINGLE SOURCE OF TRUTH for the schema-first input
+ * validation surface that powers the `mutate(operation, input)` DX
+ * (Saga T9855 / E7). Every CLEO operation that accepts structured input
+ * MUST be describable as an {@link OperationInputContract}: a JSON Schema
+ * draft-07 document, a stable operation identifier, and at least one
+ * worked example payload.
+ *
+ * Validators consume an {@link OperationInputContract} and produce a
+ * {@link ValidationResult} discriminated union — either the typed value
+ * (`ok: true`) or an array of {@link ValidationError} entries with
+ * actionable, JSON-Pointer-anchored remediation hints (`ok: false`).
+ *
+ * ZERO runtime dependencies: `contracts` is a leaf package. JSON Schema
+ * documents are modeled as the loose alias {@link JsonSchema} so this
+ * module does not pull in a JSON Schema typings package.
+ *
+ * @packageDocumentation
+ * @module @cleocode/contracts/operations/input-contract
+ *
+ * @see {@link https://json-schema.org/draft-07/schema}
+ *
+ * @epic T9855
+ * @task T9914
+ */
+
+// ---------------------------------------------------------------------------
+// JSON Schema
+// ---------------------------------------------------------------------------
+
+/**
+ * Loose alias for a JSON Schema draft-07 document.
+ *
+ * Intentionally typed as `Record<string, unknown>` to keep the contracts
+ * package free of any JSON Schema typings runtime/type dependency. The
+ * actual draft-07 shape is enforced by the validator implementation
+ * (T9915) at the point of use, not by the type system here.
+ *
+ * @example
+ * ```ts
+ * const titleSchema: JsonSchema = {
+ *   type: 'object',
+ *   required: ['title'],
+ *   properties: {
+ *     title: { type: 'string', minLength: 1 },
+ *   },
+ * };
+ * ```
+ */
+export type JsonSchema = Record<string, unknown>;
+
+// ---------------------------------------------------------------------------
+// Examples
+// ---------------------------------------------------------------------------
+
+/**
+ * A single worked example payload for an {@link OperationInputContract}.
+ *
+ * Examples are MANDATORY (the contract requires at least one) — they
+ * double as documentation for human readers AND as conformance fixtures
+ * for the validator self-test that ships with every CLEO release.
+ *
+ * @typeParam T - The validated, typed input shape produced by the contract.
+ *
+ * @example
+ * ```ts
+ * const example: OperationInputExample<{ title: string }> = {
+ *   name: 'minimal',
+ *   value: { title: 'Ship saga T9855' },
+ *   description: 'Smallest valid input — title is the only required field.',
+ * };
+ * ```
+ */
+export interface OperationInputExample<T> {
+  /**
+   * Short, human-readable identifier for the example. Conventionally
+   * kebab-case (`'minimal'`, `'with-all-fields'`, `'edge-empty-array'`).
+   */
+  name: string;
+
+  /**
+   * A concrete value that validates successfully against the contract's
+   * {@link OperationInputContract.schema | schema}. Strongly typed via
+   * the `T` generic so example tables stay in sync with the operation
+   * payload shape at compile time.
+   */
+  value: T;
+
+  /**
+   * Optional prose explaining why this example matters — what edge case
+   * it covers, what default it exercises, etc. Surfaced in generated docs.
+   */
+  description?: string;
+}
+
+// ---------------------------------------------------------------------------
+// OperationInputContract
+// ---------------------------------------------------------------------------
+
+/**
+ * Schema-first input contract for a single CLEO operation.
+ *
+ * Pairs a stable operation identifier with the JSON Schema draft-07
+ * document that describes the operation's accepted input shape, plus a
+ * non-empty (by convention) catalogue of worked examples. The validator
+ * implementation (T9915) ingests an {@link OperationInputContract} and a
+ * raw payload, returning a {@link ValidationResult}.
+ *
+ * Together with the {@link OperationInputContractRegistry}, this type is
+ * the foundation of the schema-first `mutate(operation, input)` DX
+ * surface (Saga T9855 / E7).
+ *
+ * @typeParam T - The validated, typed input shape produced when the
+ * raw payload passes validation. The generic propagates through
+ * {@link ValidationResult} so callers receive a strongly-typed `value`
+ * in the success branch.
+ *
+ * @example
+ * ```ts
+ * interface CreateTaskInput {
+ *   title: string;
+ *   acceptance: string;
+ * }
+ *
+ * const createTaskContract: OperationInputContract<CreateTaskInput> = {
+ *   operation: 'tasks.create',
+ *   schema: {
+ *     type: 'object',
+ *     required: ['title', 'acceptance'],
+ *     properties: {
+ *       title: { type: 'string', minLength: 1, maxLength: 200 },
+ *       acceptance: { type: 'string', minLength: 1 },
+ *     },
+ *     additionalProperties: false,
+ *   },
+ *   examples: [
+ *     {
+ *       name: 'minimal',
+ *       value: { title: 'Ship E7', acceptance: 'PR merged' },
+ *     },
+ *   ],
+ * };
+ * ```
+ */
+export interface OperationInputContract<T> {
+  /**
+   * Stable, fully-qualified operation identifier in
+   * `<domain>.<verb>` form (e.g. `'tasks.create'`, `'docs.publish'`).
+   * Used as the registry key in {@link OperationInputContractRegistry}.
+   */
+  operation: string;
+
+  /**
+   * JSON Schema draft-07 document describing the accepted input shape.
+   * The validator MUST treat absent properties as not-present (it does
+   * NOT inject `default` values) so callers can distinguish "user
+   * omitted" from "user supplied default".
+   */
+  schema: JsonSchema;
+
+  /**
+   * Catalogue of worked example payloads. Conventionally non-empty so
+   * generated docs always have at least one runnable sample. Each
+   * example's {@link OperationInputExample.value | value} is statically
+   * typed to the contract's `T` parameter.
+   */
+  examples: ReadonlyArray<OperationInputExample<T>>;
+}
+
+// ---------------------------------------------------------------------------
+// ValidationError
+// ---------------------------------------------------------------------------
+
+/**
+ * A single validation failure produced by the input validator.
+ *
+ * Every field is REQUIRED — there are no optional remediation hints.
+ * This shape is the wire format the `mutate` DX surface returns to
+ * callers, so it MUST be stable, machine-parseable, AND human-readable.
+ *
+ * @example
+ * ```ts
+ * const err: ValidationError = {
+ *   path: '/title',
+ *   expected: 'string with minLength 1',
+ *   received: 'empty string',
+ *   fix: 'Provide a non-empty title (1-200 chars).',
+ *   errorCode: 'E_INPUT_MIN_LENGTH',
+ *   schemaPath: '#/properties/title/minLength',
+ * };
+ * ```
+ */
+export interface ValidationError {
+  /**
+   * RFC 6901 JSON Pointer to the failing input location, anchored at
+   * the root of the payload (e.g. `'/title'`, `'/owners/0/email'`).
+   * An empty string `''` denotes the root document itself.
+   */
+  path: string;
+
+  /**
+   * Human-readable description of what the validator expected at
+   * {@link ValidationError.path | path} (e.g. `'string'`,
+   * `'integer >= 0'`, `'one of: pending | active | done'`).
+   */
+  expected: string;
+
+  /**
+   * Human-readable description of what was actually received at
+   * {@link ValidationError.path | path}. NEVER includes the raw value
+   * itself — describes type/cardinality only — so logs of errors do
+   * not accidentally leak user payloads.
+   */
+  received: string;
+
+  /**
+   * Actionable, imperative remediation hint targeted at the caller
+   * (e.g. `'Provide a non-empty title (1-200 chars).'`). Surfaced
+   * directly in CLI output and validator return envelopes.
+   */
+  fix: string;
+
+  /**
+   * Stable, screaming-snake-case error code (e.g.
+   * `'E_INPUT_MIN_LENGTH'`, `'E_INPUT_REQUIRED'`). Stable across
+   * releases so callers can branch on it programmatically.
+   */
+  errorCode: string;
+
+  /**
+   * RFC 6901 JSON Pointer into the contract's
+   * {@link OperationInputContract.schema | schema} that produced the
+   * failure (e.g. `'#/properties/title/minLength'`). Lets tooling jump
+   * straight to the offending schema clause.
+   */
+  schemaPath: string;
+}
+
+// ---------------------------------------------------------------------------
+// ValidationResult
+// ---------------------------------------------------------------------------
+
+/**
+ * Discriminated union returned by the input validator.
+ *
+ * Narrows on the `ok` boolean: when `ok === true`, the strongly-typed
+ * `value` is present; when `ok === false`, a non-empty `errors` array
+ * lists every failure (validators are encouraged to surface ALL errors
+ * in one pass, not bail on the first).
+ *
+ * @typeParam T - The validated, typed input shape produced on success.
+ *
+ * @example
+ * ```ts
+ * function handle(result: ValidationResult<{ title: string }>) {
+ *   if (result.ok) {
+ *     // result.value is { title: string }
+ *     return createTask(result.value);
+ *   }
+ *   // result.errors is ValidationError[]
+ *   for (const e of result.errors) {
+ *     console.error(`${e.path}: ${e.fix}`);
+ *   }
+ * }
+ * ```
+ */
+export type ValidationResult<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly errors: ValidationError[] };
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+/**
+ * Registry of every {@link OperationInputContract} known to the CLEO
+ * runtime, keyed by the contract's `operation` identifier (e.g.
+ * `'tasks.create'`).
+ *
+ * The value type uses `unknown` for the contract's generic so registry
+ * lookups stay assignable across operations with different input
+ * shapes. Callers that need the concrete `T` MUST narrow via an
+ * operation-specific accessor — direct `registry[op]` reads are
+ * intentionally not type-narrowed by operation name.
+ *
+ * @example
+ * ```ts
+ * const registry: OperationInputContractRegistry = {
+ *   'tasks.create': createTaskContract,
+ *   'docs.publish': publishDocsContract,
+ * };
+ *
+ * const contract = registry['tasks.create'];
+ * if (contract) {
+ *   // validate(contract, payload) → ValidationResult<unknown>
+ * }
+ * ```
+ */
+export type OperationInputContractRegistry = Record<string, OperationInputContract<unknown>>;

package/src/templates/__tests__/manifest.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Contract tests for the TemplateManifest schema.
+ *
+ * Asserts:
+ *
+ * 1. A valid entry for every {@link TemplateKind} parses successfully.
+ * 2. An entry with an unknown `kind` is rejected.
+ * 3. An entry missing `installPath` is rejected.
+ * 4. The {@link PlaceholderSpec} `source` field is exhaustively typed —
+ *    every member of {@link PLACEHOLDER_SOURCES} parses, and a bogus
+ *    source value is rejected.
+ *
+ * @task T9875
+ * @epic T9874
+ * @saga T9855
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  PLACEHOLDER_SOURCES,
+  PlaceholderSpecSchema,
+  TEMPLATE_KINDS,
+  type TemplateKind,
+  type TemplateManifestEntry,
+  TemplateManifestEntrySchema,
+} from '../manifest.js';
+
+/**
+ * Build a valid baseline entry parameterized by `kind` so each
+ * assertion below stays minimal.
+ */
+function baseEntry(kind: TemplateKind): TemplateManifestEntry {
+  return {
+    id: `sample-${kind}`,
+    kind,
+    sourcePath: `packages/core/templates/${kind}s/sample.tmpl`,
+    installPath: `.cleo/${kind}s/sample`,
+    substitution: 'regex-tmpl',
+    placeholders: [
+      {
+        name: 'NODE_VERSION',
+        source: 'project-context',
+        sourcePath: 'engines.node',
+        defaultValue: 24,
+      },
+    ],
+    updateStrategy: 'overwrite-on-bump',
+  };
+}
+
+describe('TemplateManifestEntrySchema (T9875)', () => {
+  it('accepts a valid entry for every TemplateKind', () => {
+    for (const kind of TEMPLATE_KINDS) {
+      const entry = baseEntry(kind);
+      const parsed = TemplateManifestEntrySchema.parse(entry);
+      expect(parsed.kind, `kind '${kind}' must round-trip`).toBe(kind);
+      expect(parsed.installPath).toBe(entry.installPath);
+    }
+  });
+
+  it('rejects an entry with an unknown kind', () => {
+    const bogus = {
+      ...baseEntry('workflow'),
+      kind: 'not-a-real-kind',
+    };
+    const result = TemplateManifestEntrySchema.safeParse(bogus);
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects an entry missing installPath', () => {
+    const { installPath: _drop, ...rest } = baseEntry('config');
+    const result = TemplateManifestEntrySchema.safeParse(rest);
+    expect(result.success).toBe(false);
+  });
+
+  it('accepts an entry whose placeholders array is empty', () => {
+    const entry = { ...baseEntry('doc'), placeholders: [] };
+    const result = TemplateManifestEntrySchema.safeParse(entry);
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts a defaultValue of every supported literal type and null', () => {
+    const types = [
+      { defaultValue: 'string-default' },
+      { defaultValue: 42 },
+      { defaultValue: true },
+      { defaultValue: null },
+      {},
+    ] as const;
+    for (const extra of types) {
+      const result = PlaceholderSpecSchema.safeParse({
+        name: 'X',
+        source: 'literal',
+        sourcePath: 'X',
+        ...extra,
+      });
+      expect(result.success, `defaultValue case ${JSON.stringify(extra)} must parse`).toBe(true);
+    }
+  });
+});
+
+describe('PlaceholderSpecSchema source enum (T9875)', () => {
+  it('exhaustively accepts every member of PLACEHOLDER_SOURCES', () => {
+    for (const source of PLACEHOLDER_SOURCES) {
+      const result = PlaceholderSpecSchema.safeParse({
+        name: 'PLACEHOLDER',
+        source,
+        sourcePath: 'some.path',
+      });
+      expect(result.success, `source '${source}' must parse`).toBe(true);
+    }
+  });
+
+  it('rejects an unknown source value', () => {
+    const result = PlaceholderSpecSchema.safeParse({
+      name: 'PLACEHOLDER',
+      source: 'not-a-source',
+      sourcePath: 'some.path',
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects an empty name', () => {
+    const result = PlaceholderSpecSchema.safeParse({
+      name: '',
+      source: 'project-context',
+      sourcePath: 'some.path',
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects an empty sourcePath', () => {
+    const result = PlaceholderSpecSchema.safeParse({
+      name: 'X',
+      source: 'project-context',
+      sourcePath: '',
+    });
+    expect(result.success).toBe(false);
+  });
+});