@cleocode/contracts 2026.9.9 → 2026.9.11

package/src/acceptance-gate.ts

@@ -88,9 +88,14 @@ export interface GateBase {
 // ─── Variants ────────────────────────────────────────────────────────────────
 
 /**
- * Run a command and verify its actual exit status. Positive `minCount` requires
- * a structured test-count capability and currently returns an explicit error. Designed for test suites:
+ * Run a command and verify its actual exit status. Designed for test suites:
  * `{ kind: 'test', command: 'pnpm test', expect: 'pass' }`.
+ *
+ * A positive `minCount` additionally requires the gate's OWN command to emit a
+ * machine-readable report satisfying `testCountReportSchema` (e.g. by adding
+ * `--reporter=json`). A run that emits none is an error, never a pass: an exit
+ * code carries no count, and a report file written by some other invocation is
+ * not bound to this execution.
  */
 export interface TestGate extends GateBase {
   kind: 'test';
@@ -103,7 +108,13 @@ export interface TestGate extends GateBase {
    * - `"exit0"`: exit code 0 only (permissive mode).
    */
   expect: 'pass' | 'exit0';
-  /** Minimum test count; unsupported count evidence must return error, never infer a count from exit zero. */
+  /**
+   * Minimum number of PASSING tests the run must report.
+   *
+   * Satisfied only by a structured report emitted by this gate's own command;
+   * a run that produces none returns an error rather than inferring a count
+   * from exit zero (T12308).
+   */
   minCount?: number;
   /** Working directory relative to project root. Default `.`. */
   cwd?: string;

package/src/dispatch/operations-registry.ts

@@ -1811,6 +1811,36 @@ export const OPERATIONS: OperationDef[] = [
       },
     ] satisfies ParamDef[],
   },
+  // T12308: the typed-gate runner `cleo verify <id> --run`. A query — it
+  // executes the gates and reports them, and records nothing. Documented as
+  // the canonical driver since T768 and emitted into every validation-stage
+  // spawn prompt, but the flag had been dropped from the command.
+  {
+    gateway: 'query',
+    domain: 'check',
+    operation: 'gate.run',
+    description:
+      "check.gate.run (query) — execute a task's typed acceptance gates and report results; persists nothing (T12308)",
+    tier: 1,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['taskId'],
+    params: [
+      {
+        name: 'taskId',
+        type: 'string',
+        required: true,
+        description: 'Task whose typed gates should run',
+        cli: { positional: true },
+      },
+      {
+        name: 'agent',
+        type: 'string',
+        required: false,
+        description: 'Actor attribution recorded on each gate result',
+      },
+    ] satisfies ParamDef[],
+  },
   // check.archive.stats incoming from admin (T5615)
   {
     gateway: 'query',

package/src/index.ts

@@ -43,6 +43,7 @@ export {
   httpGateSchema,
   lintGateSchema,
   manualGateSchema,
+  testCountReportSchema,
   testGateSchema,
 } from './acceptance-gate-schema.js';
 // === Provider Adapter Contracts ===
@@ -1830,6 +1831,7 @@ export type {
   ValidateComplianceViolationsResult,
   ValidateGateParams,
   ValidateGateResult,
+  ValidateGateRunResult,
   ValidateGradeListParams,
   ValidateGradeListResult,
   ValidateGradeParams,

package/src/operations/validate.ts

@@ -184,6 +184,29 @@ export interface ValidateCoherenceResult {
   warnings: string[];
 }
 
+/**
+ * Result of `check.gate.run` — typed gates executed, nothing persisted.
+ *
+ * Structurally the core preview payload; declared here so the dispatch layer
+ * narrows it without importing from core.
+ *
+ * @task T12308
+ */
+export interface ValidateGateRunResult {
+  /** Task whose typed gates were run. */
+  taskId: string;
+  /** Number of typed gates found on the acceptance array. */
+  gateCount: number;
+  /** One result per typed gate, in acceptance-array order. */
+  results: unknown[];
+  /** True when no gate returned `fail` or `error`. */
+  passed: boolean;
+  /** Always false — `--run` observes, `--evidence` attests. */
+  persisted: false;
+  /** Present when the task carries no typed gates. */
+  note?: string;
+}
+
 export interface ValidateGateParams {
   taskId: string;
   gate?: string;
@@ -365,6 +388,7 @@ export type CheckOps = {
   readonly coherence: readonly [ValidateCoherenceParams, ValidateCoherenceResult];
   readonly 'gate.status': readonly [ValidateGateParams, ValidateGateResult];
   readonly 'gate.set': readonly [ValidateGateParams, ValidateGateResult];
+  readonly 'gate.run': readonly [ValidateGateParams, ValidateGateRunResult];
   readonly 'verify.explain': readonly [ValidateVerifyExplainParams, ValidateVerifyExplainResult];
   readonly 'archive.stats': readonly [ValidateArchiveStatsParams, ValidateArchiveStatsResult];
   readonly grade: readonly [ValidateGradeParams, ValidateGradeResult];

package/src/project-context.ts

@@ -55,6 +55,23 @@ export type FileNamingConvention = 'kebab-case' | 'snake_case' | 'camelCase' | '
 /** Module import style. */
 export type ImportStyle = 'esm' | 'commonjs' | 'mixed';
 
+/**
+ * Evidence execution configured per project.
+ *
+ * @task T12308
+ */
+export interface ProjectEvidenceContext {
+  /**
+   * Checkout that `git`/`gh` evidence tools must run in, relative to the CLEO
+   * store root (an absolute path is also accepted).
+   *
+   * Needed only when the store root is not itself a git work tree AND parents
+   * more than one repository — CLEO resolves a single nested checkout, and a
+   * `commit:` atom whose SHA exists in exactly one sibling, without help.
+   */
+  gitRoot?: string;
+}
+
 /** Release and evidence behavior configured per project. */
 export interface ProjectReleaseContext {
   /** Branches whose reachable commits may satisfy `commit:` evidence atoms. */
@@ -121,6 +138,8 @@ export interface ProjectContext {
   };
   /** Release and evidence behavior for this project. */
   release?: ProjectReleaseContext;
+  /** Evidence execution overrides for this project (T12308). */
+  evidence?: ProjectEvidenceContext;
 }
 
 /**