@cleocode/contracts 2026.10.25 → 2026.10.26-rc.ci.697

package/src/acceptance-gate.ts

@@ -39,6 +39,11 @@ export interface AcceptanceGateRunOptions
   extends Pick<ProcessCaptureOptions, 'memoryMaxMb' | 'tasksMax'> {
   /** Explicit project root, or the captured operation's project root. */
   projectRoot?: string;
+  /**
+   * Task whose `task/<id>` worktree may be the tree the gates run in (T14058);
+   * absent skips that tier of `resolveTypedGateRoot`.
+   */
+  taskId?: string;
   /** Manual gates remain skipped and never become machine proof. */
   skipManual?: boolean;
   /** Original admitted operation, including project identity, deadline and cancellation. */
@@ -127,9 +132,10 @@ export interface GateBase {
  *
  * 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.
+ * `--reporter=json`), a `testCountSummarySchema` last stdout line, or node:test
+ * TAP (`--test-reporter=tap`, T14051). 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';

package/src/branch-lock.ts

@@ -200,6 +200,30 @@ export interface WorktreeIntegrationPlan {
   reason: string;
 }
 
+/**
+ * What completion knows about a task's worktree, read once through one model
+ * (T10871): where it is, which branch git has checked out there, how CLEO
+ * provisioned it, and whether it is locked or dirty.
+ */
+export interface WorktreeLifecycleState {
+  /** Task ID. */
+  taskId: string;
+  /** Worktree path: the one git has registered for the task, else the canonical one. */
+  path: string;
+  /** Branch git reports checked out there; `task/<id>` when git has no worktree for the task. */
+  branch: string;
+  /** Whether git has a worktree registered for the task. */
+  registered: boolean;
+  /** Whether the worktree directory exists on disk. */
+  exists: boolean;
+  /** Newest provisioning row in the lifecycle audit log: `create`, `adopt`, or `null` (not CLEO's). */
+  provisioning: 'create' | 'adopt' | null;
+  /** Whether git holds a lock on the worktree. */
+  locked: boolean;
+  /** Whether the worktree has uncommitted changes (`git status --porcelain` non-empty). */
+  dirty: boolean;
+}
+
 /**
  * The single integration result on the `cleo complete` envelope (T14053).
  * `action` is what happened: `merge` only when a merge commit was made.

package/src/dispatch/operations-registry.ts

@@ -4230,6 +4230,13 @@ export const OPERATIONS: OperationDef[] = [
         required: false,
         description: 'Progressive disclosure tier (0-2)',
       },
+      {
+        name: 'baseRef',
+        type: 'string',
+        required: false,
+        description:
+          'T14046: ref the task branch is created from instead of HEAD; a provisioning failure refuses the spawn',
+      },
     ],
   },
   {

package/src/done-plan.ts

@@ -74,6 +74,10 @@ export type DonePlanBlockerCode =
   | 'qa-run-needed'
   | 'ac-mapping-needed'
   | 'manual-gate'
+  /** A required gate is not passed and `cleo done` cannot derive its evidence (T14036). */
+  | 'gate-not-derivable'
+  /** A `depends` edge points at a task that is not terminal; complete refuses (T14036). */
+  | 'dependency-unresolved'
   | 'epic-rollup'
   | 'run-from-worktree'
   | 'checkout-required'

package/src/index.ts

@@ -201,6 +201,7 @@ export type {
   WorktreeIntegrationAction,
   WorktreeIntegrationOutcome,
   WorktreeIntegrationPlan,
+  WorktreeLifecycleState,
   WorktreeMergeResult,
   WorktreeSpawnResult,
 } from './branch-lock.js';
@@ -2372,6 +2373,7 @@ export type {
   MemoryConsumer,
   MemoryConsumers,
   MemoryPressureReading,
+  ProjectSettingOverride,
   ResourceClass,
   ResourceDeferral,
   ResourceGrant,

package/src/operations/output-contracts-data.ts

@@ -126,6 +126,23 @@ const tasksShowOutputContract: OperationOutputContract = {
             description: 'Human / owner assignee. Separate from `claim`.',
           },
           claim: TASK_CLAIM_SCHEMA,
+          // T14043: optional fields a record may omit. `--field` on one that is
+          // absent prints its empty value (`[]` for a list, `null` otherwise).
+          description: { type: ['string', 'null'] },
+          acceptance: {
+            type: 'array',
+            description: 'Acceptance criteria (strings or typed gates).',
+          },
+          notes: { type: 'array', description: 'Timestamped notes; absent when none.' },
+          labels: { type: 'array' },
+          files: { type: 'array', description: 'Declared files (`--files`).' },
+          depends: { type: 'array' },
+          relates: { type: 'array' },
+          size: { type: ['string', 'null'] },
+          kind: { type: ['string', 'null'] },
+          verification: { type: ['object', 'null'] },
+          completedAt: { type: ['string', 'null'] },
+          cancelledAt: { type: ['string', 'null'] },
         },
       },
       view: {
@@ -178,6 +195,7 @@ const tasksShowOutputContract: OperationOutputContract = {
     '/data/task/verification',
     '/data/task/verification/gates',
     '/data/task/verification/evidence',
+    '/data/task/notes',
     '/data/view/id',
     '/data/view/title',
   ],

package/src/resource-governor.ts

@@ -236,6 +236,23 @@ export interface HeavyLeverChange {
   readonly to: string;
 }
 
+/**
+ * A setting from a project file that the heavy-run overlay overrides (T14038),
+ * so a run that behaves differently from the project's own setup says why.
+ */
+export interface ProjectSettingOverride {
+  /** What the project set, e.g. `vitest maxWorkers` or `pnpm workspace-concurrency`. */
+  readonly setting: string;
+  /** The file that sets it, relative to the run's directory. */
+  readonly file: string;
+  /** The project's value. */
+  readonly projectValue: string;
+  /** The overlay variable that overrides it, e.g. `VITEST_MAX_WORKERS`. */
+  readonly variable: string;
+  /** The value the run gets. */
+  readonly appliedValue: string;
+}
+
 /**
  * The resource plan a memory-bound tool (`test`, `build`, and since T13123
  * `typecheck`, `lint`) was spawned with, and why (T13122). Reported by
@@ -270,6 +287,11 @@ export interface HeavyToolResourcePlan {
   readonly kept: readonly string[];
   /** `true` when explicit `CLEO_HEAVY_*` overrides put the run over {@link budgetMb}. */
   readonly overBudget: boolean;
+  /**
+   * Settings the project's own files make that the overlay overrides (T14038):
+   * vitest `maxWorkers`, pnpm `workspace-concurrency`. Absent when none.
+   */
+  readonly projectOverrides?: readonly ProjectSettingOverride[];
   /** One line naming the heap and worker count chosen and why. */
   readonly summary: string;
 }

package/src/task.ts

@@ -172,6 +172,10 @@ export interface EvidenceMergeAnchor {
   mergedAt: string;
   /** Paths the PR changed. */
   changedPaths?: readonly string[];
+  /** Paths the PR deleted: absent from its merge tree, so never `files:` artifacts (T14030). */
+  deletedPaths?: readonly string[];
+  /** The PR's number, named when a `files:` path it deleted is refused (T14030). */
+  prNumber?: number;
 }
 
 /** Task and criterion scope used while validating evidence, independent of PR metadata. */
@@ -198,6 +202,13 @@ export interface EvidenceValidationContext {
    * Takes precedence over {@link EvidenceValidationContext.artifactCommitSha}.
    */
   artifactPrs?: ReadonlyArray<EvidenceMergeAnchor>;
+  /**
+   * Every `test-run:` path in the evidence write (T14031). A report's coverage
+   * of the change is judged over the test files all of them passed, so a
+   * vitest report and a Playwright report together cover unit and e2e files;
+   * each report is still validated on its own.
+   */
+  testRunPaths?: readonly string[];
   /**
    * Validate without persisting anything: `pr:`/`ci:` lookups write neither
    * the PR-result cache nor the branch-protection cache (T12671 review — the
@@ -463,6 +474,12 @@ export type EvidenceAtom =
        * every uncommitted, not-ignored change applied.
        */
       treeHash?: string;
+      /**
+       * HEAD of the checkout the run measured (T13003). With `treeHash` it lets
+       * verify and complete refuse a run whose checkout lacks the task's
+       * implemented commits. Absent on atoms recorded before T13003.
+       */
+      headSha?: string;
       /** `true` when the result was served from the tool cache (no spawn). */
       cacheHit?: boolean;
       /**
@@ -675,6 +692,24 @@ export type EvidenceAtom =
        * merge-commit run.
        */
       nonTestFailures?: Array<{ name: string; mergeRunId: number }>;
+      /**
+       * The merge commit's own run FAILED, but every failing job failed with
+       * no failed test: its runner was cancelled (T14049) or a vitest worker
+       * crashed (T14074). `descendantSha` is the later green main run standing
+       * in. Each job records its failing merge-commit run and the cause.
+       */
+      untestedFailures?: Array<{
+        name: string;
+        mergeRunId: number;
+        cause: 'runner-cancel' | 'worker-crash';
+      }>;
+      /**
+       * Later default-branch runs the stand-in search looked past before
+       * `descendantSha`, and why (T14086): the flaky-quarantine budget stopped
+       * them before their flake rerun, so a quarantined failure or a test that
+       * only timed out decided nothing.
+       */
+      passedOverRuns?: Array<{ sha: string; jobs: string[]; reason: string }>;
       /**
        * The PR edited a pinned workflow, so only default-branch `push` runs
        * attested it; its own `pull_request` runs (which ran the edited