@cleocode/contracts 2026.10.27 → 2026.11.1-canary.2

package/src/project-context.ts

@@ -11,6 +11,8 @@
  * @adr ADR-013
  */
 
+import type { VerificationGate } from './task.js';
+
 /** Detected project ecosystem. Matches the writer in `detectProjectType`. */
 export type ProjectType =
   | 'node'
@@ -78,6 +80,14 @@ export interface ProjectEvidenceContext {
    * @task T12634
    */
   ciSatisfies?: boolean;
+  /**
+   * Gates a probed `deploy:` atom satisfies (T14083). No default: unset or
+   * empty, a deploy atom satisfies nothing, and never `testsPassed` unless
+   * listed here.
+   *
+   * @task T14083
+   */
+  deploySatisfies?: VerificationGate[];
   /**
    * Which required checks attest each gate for `ci:<pr>`. Each list must be a
    * subset of the required-check list; a gate without a list refuses `ci:`.
@@ -106,6 +116,24 @@ export interface ProjectEvidenceContext {
    * refused (E_EVIDENCE_RUNTIME_PATH_PROTECTED). Default: none.
    */
   runtimePaths?: string[];
+  /**
+   * Further git repositories this project's evidence may come from (an SDK in
+   * a separate repository, T14078). A typed gate names one by `repo`; any
+   * repository not declared here is refused.
+   */
+  repositories?: EvidenceRepositoryDeclaration[];
+}
+
+/**
+ * A git repository outside the project that typed gates may run in (T14078).
+ */
+export interface EvidenceRepositoryDeclaration {
+  /** Name a typed gate's `repo` field uses. */
+  name: string;
+  /** The checkout's root, relative to the CLEO store root or absolute. */
+  path: string;
+  /** Why the project's evidence comes from it. */
+  purpose: string;
 }
 
 /**
@@ -163,6 +191,11 @@ export interface ProjectContext {
   build?: {
     command?: string;
     outputDir?: string;
+    /**
+     * Globs, relative to the project root, of scripts that run heavy tools:
+     * `cleo run` charges them as heavy whatever their content shows (T14162).
+     */
+    heavyScripts?: string[];
   };
   directories?: {
     source?: string;

package/src/release/authorization.ts

@@ -0,0 +1,48 @@
+/**
+ * Standing release authorization (T14141 · owner decision D11215): a grant the
+ * owner signs with the enrolled owner key so a non-interactive
+ * `cleo release cut --yes` (an agent) may tag without a typed terminal
+ * confirmation.
+ *
+ * @task T14141
+ */
+
+/**
+ * What a grant covers: `canary` (`-canary.N` versions), `prerelease` (any
+ * `-suffix`), `stable` (no suffix), or one exact `v`-prefixed version.
+ */
+export type ReleaseAuthorizationScope = 'canary' | 'prerelease' | 'stable' | `v${string}`;
+
+/** One owner-signed standing release authorization. */
+export interface ReleaseAuthorizationGrant {
+  /** Grant id (`ra-<hex>`), named in the cut audit row and the tag message. */
+  id: string;
+  /** Versions the grant covers. */
+  scope: ReleaseAuthorizationScope;
+  /** Why the owner granted it. */
+  reason: string;
+  /** ISO time the grant was issued. */
+  issuedAt: string;
+  /** ISO time it stops counting (at most 30 days after issue). */
+  expiresAt: string;
+  /** Optional cap on cuts it may allow; null = no limit (D11215). */
+  uses: number | null;
+  /** The owner decision recorded for the grant (BRAIN decision id). */
+  decisionId: string;
+  /** Revocations on record when it was issued; a shorter revocation list later means tampering. */
+  revocationsAtIssue: number;
+  /** Enrolled owner public key (hex) that signed it. */
+  ownerPubkey: string;
+  /** Ed25519 signature (hex) over the grant's fields. */
+  sig: string;
+}
+
+/** A grant as `cleo release authorize --list` reports it. */
+export interface ReleaseAuthorizationStatus extends ReleaseAuthorizationGrant {
+  /** Whether it currently allows a cut, and if not why. */
+  state: 'active' | 'expired' | 'used-up' | 'revoked' | 'tampered';
+  /** Cuts it has allowed (audit rows and tags naming it). */
+  used: number;
+  /** Why it is tampered, when it is. */
+  why?: string;
+}

package/src/review-verdict.ts

@@ -0,0 +1,122 @@
+/**
+ * Independent per-AC review of a PR (T14122, council run
+ * 20261028T155822Z-293ed9f0, blocking amendment 2 of D11211).
+ *
+ * A reviewer other than the task's author judges each acceptance criterion
+ * from the PR diff and the criterion text alone, and records a verdict under
+ * its own CLEO session, bound to the PR head it reviewed. The merge sweep
+ * (T14101) records `satisfies:` only from a `met` verdict on the merged head;
+ * PR text can neither create nor waive one.
+ *
+ * @task T14122
+ */
+
+/** One acceptance criterion as a reviewer sees it: its alias and its text. */
+export interface ReviewPacketCriterion {
+  /** `AC1`, `AC2`, … */
+  alias: string;
+  /** The criterion text. */
+  text: string;
+}
+
+/**
+ * What a reviewer is given for one PR and task: the diff at the PR head and
+ * the task's criteria. The PR title, body, comments and commit messages are
+ * never included, so the author's `Closes:` / `Refs:` lines and summary cannot
+ * reach the reviewer.
+ */
+export interface ReviewPacket {
+  /** The PR. */
+  prNumber: number;
+  /** The PR head the diff was taken at (`headRefOid`). */
+  headSha: string;
+  /** The task under review. */
+  taskId: string;
+  /** The task's criteria, in ordinal order. */
+  acs: ReviewPacketCriterion[];
+  /** The PR diff at `headSha`, without the paths in `withheldPaths`. */
+  diff: string;
+  /** Changed paths left out of `diff` because they carry the author's own account (changesets). */
+  withheldPaths: string[];
+  /** sha256 of the head, the criteria and the diff: a verdict names it to prove what was reviewed. */
+  packetSha256: string;
+}
+
+/** The identities that authored a task: its claim holders and the session that created it. */
+export interface ReviewAuthors {
+  /** CLEO session ids. */
+  sessionIds: string[];
+  /** Agent ids (`CLEO_AGENT_ID`, spawn handles). */
+  agentIds: string[];
+}
+
+/** One reviewer's verdict on one criterion of one task, for one PR head. */
+export interface ReviewVerdict {
+  /** Verdict id (uuid). */
+  id: string;
+  /** The task. */
+  taskId: string;
+  /** The criterion alias (`AC2`). */
+  ac: string;
+  /** The criterion's stable id (`task_acceptance_criteria.id`). */
+  acId: string;
+  /** The PR. */
+  prNumber: number;
+  /** The PR head the reviewer judged (`headRefOid`), never the merge sha. */
+  headSha: string;
+  /** Whether the diff implements the criterion. */
+  verdict: 'met' | 'unmet';
+  /** Why, in the reviewer's words. */
+  reason: string;
+  /** Who reviewed: never one of `authors`. */
+  reviewer: { sessionId: string; agentId: string | null };
+  /** The task's authors when the verdict was recorded, so a reader can re-check independence. */
+  authors: ReviewAuthors;
+  /** The {@link ReviewPacket.packetSha256} the reviewer was given. */
+  packetSha256: string;
+  /**
+   * The id of an earlier non-author `unmet` verdict on the same head that
+   * this `met` answers (T14128). Without it, a later `met` cannot clear that
+   * `unmet`, so shopping for a friendlier reviewer stays visible.
+   */
+  answers?: string;
+  /** ISO-8601 time it was recorded. */
+  createdAt: string;
+}
+
+/** Why one criterion has no usable verdict on a head. */
+export interface ReviewGap {
+  /** The criterion alias. */
+  ac: string;
+  /**
+   * `missing`: none recorded; `unmet`: the latest says unmet; `stale`: only
+   * older heads have one; `author`: the latest on the head came from one of
+   * the task's own authors (a re-check of the record-time refusal).
+   */
+  kind: 'missing' | 'unmet' | 'stale' | 'author';
+  /** A one-line reason, e.g. `AC2: no verdict on head abc1234 (latest is for 9f00e12)`. */
+  reason: string;
+}
+
+/**
+ * An `unmet` verdict a later `met` answered on the same head (T14137), so an
+ * owner can see who cleared whose finding.
+ */
+export interface ReviewAnswer {
+  /** The criterion. */
+  ac: string;
+  /** The answered `unmet` verdict and its reviewer. */
+  unmet: { id: string; reviewer: ReviewVerdict['reviewer'] };
+  /** The `met` verdict that answered it and its reviewer. */
+  met: { id: string; reviewer: ReviewVerdict['reviewer'] };
+}
+
+/** The criteria a set of verdicts proves met on a head, and the gaps. */
+export interface ReviewJudgement {
+  /** The head judged against. */
+  headSha: string;
+  /** Criteria whose latest verdict on `headSha` is `met`. */
+  met: string[];
+  /** Criteria without a `met` verdict on `headSha`, each with why. */
+  gaps: ReviewGap[];
+}

package/src/session-journal.ts

@@ -112,7 +112,13 @@ export const sessionJournalEntrySchema = z.object({
   tasksCompleted: z.array(z.string()).optional(),
 
   // Doctor summary (T1262 absorbed)
-  /** Compact result of `scanBrainNoise` run at session-end. */
+  /**
+   * Compact result of `scanBrainNoise` run at session-end.
+   *
+   * @deprecated T14120: no longer written. Session end stopped running the
+   * brain scan (it held `cleo session end` for ~120 s on a large store); kept
+   * so older journal entries still parse. Use `cleo memory doctor`.
+   */
   doctorSummary: sessionJournalDoctorSummarySchema.optional(),
 
   // Debrief summary

package/src/task-record.ts

@@ -8,7 +8,7 @@
  * @epic T4654
  */
 
-import type { AcceptanceItem, TaskVerification } from './task.js';
+import type { AcceptanceItem, TaskClaim, TaskVerification } from './task.js';
 
 /** Omitted source fields and their UTF-8 serialized sizes on partial records. */
 export interface RecordProjectionDisclosure {
@@ -119,6 +119,11 @@ export interface TaskRecord extends RecordProjectionDisclosure {
    * @task T944
    */
   severity?: string | null;
+  /**
+   * The agent work lease held on this task (T12502); absent when unclaimed.
+   * Surfaced so `cleo show` reads back what `cleo claim` wrote (T14165).
+   */
+  claim?: TaskClaim;
 }
 
 /**

package/src/task.ts

@@ -209,6 +209,17 @@ export interface EvidenceValidationContext {
    * each report is still validated on its own.
    */
   testRunPaths?: readonly string[];
+  /**
+   * The task's criteria this write names with `satisfies:<task>#AC…` (T14094),
+   * with their `AC<n>` alias. A merged PR of another task links to this task
+   * only through them: each must name the files the PR changed, and none may
+   * have been written or edited after the PR merged (`createdAt` and
+   * `updatedAt`: an edit gives a criterion a new row). Both are UTC ISO-8601
+   * with a zone, normalised by the writer from the store's zoneless text.
+   */
+  creditedCriteria?: ReadonlyArray<
+    Pick<AcRow, 'id' | 'text' | 'createdAt' | 'updatedAt'> & { alias: string }
+  >;
   /**
    * Validate without persisting anything: `pr:`/`ci:` lookups write neither
    * the PR-result cache nor the branch-protection cache (T12671 review — the
@@ -353,9 +364,9 @@ export type EvidenceAtom =
        */
       runtimeExcluded?: string[];
       /**
-       * Untracked files outside every directory the change touches, which the
-       * binding did not judge as this change (T14000): another agent's work
-       * in a shared checkout. The tree hash includes them, so `cleo complete`
+       * Untracked files the binding did not judge as this change (T14000,
+       * T14125): anything not committed or staged, such as another agent's
+       * work in a shared checkout. The tree hash includes them, so `cleo complete`
        * and the superseded check refuse this atom as stale once any of them
        * is tracked (committed into the change): the run never covered it.
        */
@@ -396,6 +407,13 @@ export type EvidenceAtom =
       nonCodeChange?: boolean;
       /** Untracked files set aside at bind time, as for `test-run` (T14000). */
       untrackedSetAside?: string[];
+      /**
+       * The changed paths each check reads, judged at bind time (T14089): a
+       * check with none is not owed (a `.mjs`-only change owes no typecheck).
+       * Absent on receipts bound before T14089, or when nothing was judged:
+       * then both checks are owed.
+       */
+      owedChecks?: { typecheck: string[]; lint: string[] };
     }
   | {
       kind: 'tool';
@@ -463,6 +481,12 @@ export type EvidenceAtom =
       untestedPackages?: string[];
       /** Changed CLEO config this result leaves to `tool:config-schema` in the same gate write (T13778). */
       configPaths?: string[];
+      /**
+       * Untracked files a scoped `tool:test`/`tool:test-affected` result did
+       * not judge as this change (T14125), as on a test-run atom: `cleo
+       * complete` refuses the result once any of them is tracked.
+       */
+      untrackedSetAside?: string[];
       /**
        * Test files that failed and then passed on their single retry
        * (T12961). The run counts as a pass; this marks it as a FLAKY pass so
@@ -734,6 +758,80 @@ export type EvidenceAtom =
       /** Where the required-check list came from (env, project context, branch protection). */
       requiredSource: string;
     }
+  | {
+      /**
+       * A green run of `.github/workflows/repeat-run.yml` (T14149): one test
+       * file run `runs` times on the default branch, every run passing. Read
+       * from GitHub (workflow, event, branch, latest attempt) and cross-checked
+       * against the run's uploaded report. `headSha` must contain the task's
+       * implemented commits; the test file must be one the task changed or one a
+       * linked criterion names. It links criteria; it does not satisfy
+       * `testsPassed` on its own.
+       *
+       * @task T14149
+       */
+      kind: 'ci-run';
+      /** GitHub Actions run id. */
+      runId: number;
+      /** Commit the run tested (the run's `head_sha` on the default branch). */
+      headSha: string;
+      /** Repo-relative test file the run repeated. */
+      test: string;
+      /** How many consecutive runs passed. */
+      runs: number;
+      /** Run attempt that was judged (the latest). */
+      attempt: number;
+      /** Workflow file of the run. */
+      workflow: string;
+      /** Task the atom was verified for. */
+      taskId?: string;
+    }
+  | {
+      /**
+       * Probed deployment (T14083, owner decision on option (a)): at verify
+       * time CLEO ran a bounded GET of `probeUrl`, it returned 2xx and named
+       * the deployed SHA in its body or an `X-Commit` / `X-Version` header.
+       * `headSha` must contain the task's implemented commits (ancestor or
+       * patch-equivalent); `cleo complete` re-checks only that, never the probe.
+       * Satisfies only the gates in `satisfiesGates`, the project's
+       * `evidence.deploySatisfies` at verify time.
+       *
+       * @task T14083
+       */
+      kind: 'deploy';
+      /** Provider name as given (`railway`, `fly`, …); recorded, not verified. */
+      provider: string;
+      /** Provider deployment id as given; recorded, not verified. */
+      deploymentId: string;
+      /** The deployed commit, resolved to its full SHA. */
+      headSha: string;
+      /** The URL that was probed. */
+      probeUrl: string;
+      /** The probe's result. */
+      probe: {
+        /** HTTP status (2xx). */
+        status: number;
+        /** ISO 8601 time the probe completed. */
+        probedAt: string;
+        /** sha256 of the (bounded) response body read. */
+        bodySha256: string;
+        /** Where the SHA was named: `x-commit`, `x-version` or `body`. */
+        shaSource: 'x-commit' | 'x-version' | 'body';
+      };
+      /** The gates this atom satisfies (`evidence.deploySatisfies` at verify time). */
+      satisfiesGates: VerificationGate[];
+      /**
+       * The provider's own word on the deployment (T14091): `verified: true`
+       * when its API confirmed the deployment is live and was built from
+       * `headSha`; `verified: false` (with why) when no adapter or credential
+       * let CLEO ask, and only the probe stands. Absent on atoms before T14091.
+       */
+      providerCheck?:
+        | { verified: true; status: string; commitSha: string; checkedAt: string }
+        | { verified: false; reason: string };
+      /** Task the atom was verified for. */
+      taskId?: string;
+    }
   | {
       /**
        * Satisfies atom — cross-task acceptance-criterion binding per
@@ -802,6 +900,29 @@ export interface GateEvidence {
   override?: boolean;
   /** Reason given for an override (`CLEO_OWNER_OVERRIDE_REASON` env). */
   overrideReason?: string;
+  /**
+   * Why a scoped run recorded after the merge stands in for this gate where
+   * the change alone would have needed a whole-suite run (T14163). Written by
+   * `cleo complete` when it accepts the stand-in, so the reason outlives the
+   * command's output.
+   */
+  standIn?: GateStandIn;
+}
+
+/**
+ * A recorded post-merge stand-in (T14163): a manifest-only workspace change
+ * (root `package.json` dependency fields and the pnpm lockfile) scoped by the
+ * lockfile importers its merge changed.
+ */
+export interface GateStandIn {
+  /** The stand-in rule that applied. */
+  kind: 'manifest-scoped';
+  /** The merge commit whose lockfile diff was read. */
+  mergeCommit: string;
+  /** Lockfile importers the merge changed; `.` is the root, every package. */
+  importers: string[];
+  /** ISO 8601 time `cleo complete` recorded it. */
+  recordedAt: string;
 }
 
 /** Task verification state. */