@cleocode/contracts 2026.9.25 → 2026.9.26

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

@@ -118,7 +118,7 @@ const tasksShowOutputContract: OperationOutputContract = {
           updatedAt: {
             type: ['string', 'null'],
             description:
-              'Task version for optimistic concurrency: pass it to `cleo update|complete --if-match`.',
+              'Task version for optimistic concurrency: pass it to `cleo update|complete --if-match`. A stale version fails with E_CONFLICT (23); E_TASK_RENAMED (26) when sync re-numbered the task you read (details.expected is its new id).',
           },
           // T12502: the human assignee and the agent claim lease are separate.
           assignee: {

package/src/operations/tasks.ts

@@ -1616,7 +1616,13 @@ export interface TasksUpdateQueryParams {
   /**
    * Optimistic-concurrency guard: the task `updatedAt` the caller read. When
    * the stored version differs, the update fails with `E_CONFLICT` and the
-   * current version, instead of overwriting a newer write. @task T12503
+   * current version, instead of overwriting a newer write. When sync
+   * re-numbered the task the caller read (a display-id collision) and the
+   * version is exactly the one it had under this id, the update fails with
+   * `E_TASK_RENAMED` (exit 26) instead, `details.expected` naming the task's
+   * new id; nothing is written to the task that holds the id now.
+   * @task T12503
+   * @task T12800
    */
   expectedUpdatedAt?: string;
 }
@@ -1702,8 +1708,11 @@ export interface TasksCompleteQueryParams {
   /**
    * Optimistic-concurrency guard (`--if-match`): the task `updatedAt` the
    * caller read. When the stored version differs, completion fails with
-   * `E_CONFLICT` carrying the current version and the changed fields.
+   * `E_CONFLICT` carrying the current version and the changed fields, or
+   * with `E_TASK_RENAMED` (exit 26, `details.expected` = the new id) when
+   * sync re-numbered the task the caller read.
    * @task T12503
+   * @task T12800
    */
   expectedUpdatedAt?: string;
 }

package/src/task.ts

@@ -160,6 +160,19 @@ export type VerificationGate =
    */
   | 'nexusImpact';
 
+/**
+ * The part of a verified `pr:` atom that anchors `files:` bytes: its merge
+ * commit, when it merged, and what it changed (T12848).
+ */
+export interface EvidenceMergeAnchor {
+  /** Merge commit SHA whose tree holds the PR's artifact bytes. */
+  mergeCommitSha: string;
+  /** ISO 8601 merge timestamp; the latest merge wins when several PRs changed a path. */
+  mergedAt: string;
+  /** Paths the PR changed. */
+  changedPaths?: readonly string[];
+}
+
 /** Task and criterion scope used while validating evidence, independent of PR metadata. */
 export interface EvidenceValidationContext {
   /** Canonical current task intent; prose is never interpreted as a file declaration. */
@@ -168,8 +181,22 @@ export interface EvidenceValidationContext {
   gates: readonly VerificationGate[];
   /** Canonical criteria read for this verification operation. */
   criteria: ReadonlyArray<Pick<AcRow, 'id' | 'text' | 'updatedAt'>>;
-  /** Verified PR merge whose immutable artifact bytes must be inspected. */
+  /**
+   * Verified PR merge whose immutable artifact bytes must be inspected.
+   *
+   * @deprecated Since T12848 no caller sets it: a single SHA cannot anchor a
+   * write with several `pr:` atoms. Use {@link EvidenceValidationContext.artifactPrs},
+   * which anchors each `files:` path at the merge of the PR that changed it.
+   * Still honoured when `artifactPrs` is absent.
+   */
   artifactCommitSha?: string;
+  /**
+   * Every verified PR in the evidence write (T12848). When non-empty, each
+   * `files:` path is inspected at the merge commit of the PR that changed it,
+   * so several `pr:` atoms in one write each anchor their own artifacts.
+   * Takes precedence over {@link EvidenceValidationContext.artifactCommitSha}.
+   */
+  artifactPrs?: ReadonlyArray<EvidenceMergeAnchor>;
   /**
    * Validate without persisting anything: `pr:`/`ci:` lookups write neither
    * the PR-result cache nor the branch-protection cache (T12671 review — the