@cleocode/contracts 2026.10.27 → 2026.11.1-canary.3

package/src/evidence-atom-schema.ts

@@ -64,6 +64,8 @@ export const EVIDENCE_ATOM_KINDS = [
   'decision',
   'pr',
   'ci',
+  'ci-run',
+  'deploy',
   'loc-drop',
   'callsite-coverage',
   'satisfies',
@@ -81,6 +83,12 @@ const PARSER_PREFIXES = [...EVIDENCE_ATOM_KINDS, 'state'] as const;
  */
 const KIND_BOUNDARY_REGEX = new RegExp(`;(?=\\s*(?:${PARSER_PREFIXES.join('|')})\\s*:)`, 'g');
 
+/** A `deploy:` provider name (T14083): lowercase, e.g. `railway`, `fly`, `cloudflare-pages`. */
+const DEPLOY_PROVIDER_REGEX = /^[a-z0-9][a-z0-9._-]*$/;
+
+/** A `deploy:` deployment id (T14083): no whitespace, `@` or `|`. */
+const DEPLOY_ID_REGEX = /^[^\s@|]+$/;
+
 // ---------------------------------------------------------------------------
 // Per-atom Zod schemas
 // ---------------------------------------------------------------------------
@@ -262,6 +270,47 @@ export const ciAtomSchema = z.object({
     .optional(),
 });
 
+/**
+ * `ci-run:<runId>` atom (T14149): a run of the `repeat-run.yml` workflow
+ * (dispatched on the default branch) that ran one test file N times, all green.
+ * Validated from GitHub's record of the run and its uploaded report, never from
+ * a file the agent supplies. It links an acceptance criterion that needs a heavy
+ * or repeated run; it does not satisfy `testsPassed` on its own.
+ *
+ * Format: `ci-run:<positive integer run id>` (e.g. `ci-run:40812345678`).
+ *
+ * @task T14149
+ */
+export const ciRunAtomSchema = z.object({
+  kind: z.literal('ci-run'),
+  runId: z.number().int().positive('ci-run atom requires a positive integer run id'),
+});
+
+/**
+ * `deploy:<provider>/<deploymentId>@<sha>|<probe-url>` atom (T14083): a
+ * deployment of commit `<sha>`, proven at verify time by a bounded GET of
+ * `<probe-url>` that returns 2xx and names `<sha>` in its body or in an
+ * `X-Commit` / `X-Version` header. Satisfies only the gates the project lists
+ * in `evidence.deploySatisfies` (no default).
+ *
+ * Format: `deploy:railway/9f3c2a@1a2b3c4d|https://api.example.com/health`.
+ * The provider and deployment id are recorded as given; the probe, not the
+ * provider, is the proof.
+ *
+ * @task T14083
+ */
+export const deployAtomSchema = z.object({
+  kind: z.literal('deploy'),
+  provider: z
+    .string()
+    .regex(DEPLOY_PROVIDER_REGEX, 'deploy atom provider must be a lowercase name'),
+  deploymentId: z.string().regex(DEPLOY_ID_REGEX, 'deploy atom requires a deployment id'),
+  sha: z.string().regex(/^[0-9a-f]{7,40}$/, 'deploy atom sha must be 7-40 lowercase hex chars'),
+  probeUrl: z
+    .string()
+    .regex(/^https?:\/\/\S+$/, 'deploy atom probe url must start with http:// or https://'),
+});
+
 /**
  * `loc-drop:<fromLines>:<toLines>` atom — proves that a migrated engine shed
  * lines. Required for the `implemented` gate when the task carries the
@@ -428,6 +477,8 @@ export const satisfiesAtomSchema = z.object({
  *   - `note`               — free-form note (T832)
  *   - `decision`           — brain_decisions row reference (T1875)
  *   - `pr`                 — merged-PR retroactive proof (T9764 / T9838)
+ *   - `ci-run`             — a green repeat-run.yml run of one test file (T14149)
+ *   - `deploy`             — probed deployment of a commit (T14083)
  *   - `loc-drop`           — engine-migration LOC reduction (T1604)
  *   - `callsite-coverage`  — exported-symbol production callsite (T1605)
  *   - `satisfies`          — cross-task AC binding (T10506 / ADR-079-r2;
@@ -447,6 +498,8 @@ export const EvidenceAtomSchema = z.discriminatedUnion('kind', [
   decisionAtomSchema,
   prAtomSchema,
   ciAtomSchema,
+  ciRunAtomSchema,
+  deployAtomSchema,
   locDropAtomSchema,
   callsiteCoverageAtomSchema,
   satisfiesAtomSchema,
@@ -546,10 +599,59 @@ export const GATE_EVIDENCE_REQUIREMENTS: Readonly<
   nexusImpact: { oneOf: [['tool'], ['note']] },
 });
 
+/**
+ * The gate profiles a task with no code change may declare as a
+ * `profile:<name>` label (T13474): operations work, a decision, a census or
+ * an audit. The closed set lives here so the gate requirements below and the
+ * label rules in core read one list.
+ *
+ * @task T13474
+ * @task T14187
+ */
+export const GATE_PROFILE_NAMES = ['ops', 'decision', 'census', 'audit'] as const;
+
+/** One of {@link GATE_PROFILE_NAMES}. */
+export type GateProfileName = (typeof GATE_PROFILE_NAMES)[number];
+
+/**
+ * Atom combinations a gate accepts IN ADDITION to
+ * {@link GATE_EVIDENCE_REQUIREMENTS} for a task that declares a gate profile
+ * and whose change touches no code (T14187). An operations, census or audit
+ * task (a live-data repair, a measurement) has no commit, PR or decision to
+ * cite: its proof is the stored document recording what was done or found,
+ * so `implemented` also accepts `files` (that document) with a `note`. A
+ * decision task still proves itself with its decision. Core applies this
+ * only when every `files:` path is a document, so a code change still owes a
+ * commit or PR. `cleo done --plan` and the gates read this one table.
+ *
+ * @task T14187
+ */
+export const PROFILE_GATE_EVIDENCE: Readonly<
+  Record<
+    GateProfileName,
+    Partial<Record<VerificationGate, ReadonlyArray<ReadonlyArray<EvidenceAtomKind>>>>
+  >
+> = Object.freeze({
+  ops: { implemented: [['files', 'note']] },
+  decision: {},
+  census: { implemented: [['files', 'note']] },
+  audit: { implemented: [['files', 'note']] },
+});
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
+/** The combinations `gate` accepts, with a gate profile's additions. */
+function gateCombinations(
+  gate: VerificationGate,
+  profile?: GateProfileName | null,
+): ReadonlyArray<ReadonlyArray<EvidenceAtomKind>> {
+  const base = GATE_EVIDENCE_REQUIREMENTS[gate]?.oneOf ?? [];
+  const extra = profile ? (PROFILE_GATE_EVIDENCE[profile][gate] ?? []) : [];
+  return [...base, ...extra];
+}
+
 /**
  * Result of {@link validateEvidenceForGate}.
  *
@@ -582,9 +684,13 @@ export type EvidenceValidationResult = { readonly ok: true } | EvidenceValidatio
  *
  * @task T10337
  */
-export function formatGateRequirement(gate: VerificationGate): string {
-  const requirement = GATE_EVIDENCE_REQUIREMENTS[gate];
-  return requirement.oneOf.map((set) => `[${set.join(' AND ')}]`).join(' OR ');
+export function formatGateRequirement(
+  gate: VerificationGate,
+  profile?: GateProfileName | null,
+): string {
+  return gateCombinations(gate, profile)
+    .map((set) => `[${set.join(' AND ')}]`)
+    .join(' OR ');
 }
 
 /**
@@ -605,6 +711,8 @@ const ATOM_EXAMPLES: Readonly<Record<EvidenceAtomKind, string>> = Object.freeze(
   decision: 'decision:D-arch-001',
   pr: 'pr:357',
   ci: 'ci:357',
+  'ci-run': 'ci-run:<runId>',
+  deploy: 'deploy:<provider>/<deploymentId>@<sha>|https://<host>/health',
   'loc-drop': 'loc-drop:<fromLines>:<toLines>',
   'callsite-coverage': 'callsite-coverage:<symbolName>:<relativeSourcePath>',
   satisfies: 'satisfies:T1234#AC2',
@@ -654,16 +762,20 @@ function renderCombinationAsEvidence(combination: ReadonlyArray<EvidenceAtomKind
  * @task T9949
  * @adr ADR-051 §2.3
  */
-export function formatGateRequirementHint(gate: VerificationGate): string {
+export function formatGateRequirementHint(
+  gate: VerificationGate,
+  profile?: GateProfileName | null,
+): string {
   const requirement = GATE_EVIDENCE_REQUIREMENTS[gate];
   if (!requirement) {
     // Unknown gate — match validateEvidenceForGate's defensive default.
     return `Gate '${gate}' has no documented evidence requirements.`;
   }
+  const oneOf = gateCombinations(gate, profile);
 
   const lines: string[] = [
     `Gate '${gate}' requires programmatic evidence. Use ONE of:`,
-    ...requirement.oneOf.map(
+    ...oneOf.map(
       (combo) =>
         `  - cleo verify T#### --gate ${gate} --evidence '${renderCombinationAsEvidence(combo)}'`,
     ),
@@ -671,16 +783,12 @@ export function formatGateRequirementHint(gate: VerificationGate): string {
 
   // Note-specific clarification — T9949's headline pain point.
   // The gate accepts note: alone IFF some single-element combination is ['note'].
-  const noteAloneAccepted = requirement.oneOf.some(
-    (combo) => combo.length === 1 && combo[0] === 'note',
-  );
+  const noteAloneAccepted = oneOf.some((combo) => combo.length === 1 && combo[0] === 'note');
   if (noteAloneAccepted) {
     lines.push(`Note: 'note:' alone IS accepted for this gate (waiver-style evidence).`);
   } else {
     // Surface every alternative pairing involving note for at-a-glance routing.
-    const notePairings = requirement.oneOf.filter(
-      (combo) => combo.length > 1 && combo.includes('note'),
-    );
+    const notePairings = oneOf.filter((combo) => combo.length > 1 && combo.includes('note'));
     if (notePairings.length > 0) {
       const partners = Array.from(
         new Set(notePairings.flatMap((combo) => combo.filter((k) => k !== 'note'))),
@@ -715,6 +823,8 @@ export function formatGateRequirementHint(gate: VerificationGate): string {
  *
  * @param gate - Verification gate being checked.
  * @param atoms - Already-parsed evidence atoms.
+ * @param profile - The task's gate profile when its change touches no code
+ *   ({@link PROFILE_GATE_EVIDENCE}, T14187); omit otherwise.
  * @returns Pass / fail with a human-readable failure message.
  *
  * @example
@@ -731,6 +841,7 @@ export function formatGateRequirementHint(gate: VerificationGate): string {
 export function validateEvidenceForGate(
   gate: VerificationGate,
   atoms: ReadonlyArray<{ kind: EvidenceAtomKind }>,
+  profile?: GateProfileName | null,
 ): EvidenceValidationResult {
   const requirement = GATE_EVIDENCE_REQUIREMENTS[gate];
   if (!requirement) {
@@ -738,18 +849,18 @@ export function validateEvidenceForGate(
     // behavior from checkGateEvidenceMinimum when the gate had no entry).
     return { ok: true };
   }
-  for (const combination of requirement.oneOf) {
+  for (const combination of gateCombinations(gate, profile)) {
     const satisfied = combination.every((kind) => atoms.some((a) => a.kind === kind));
     if (satisfied) return { ok: true };
   }
   return {
     ok: false,
-    message: `Gate '${gate}' requires evidence: ${formatGateRequirement(gate)}`,
+    message: `Gate '${gate}' requires evidence: ${formatGateRequirement(gate, profile)}`,
     // T9949: rich, example-bearing remediation hint suitable for CLI `fix:`.
     // Always populated alongside `message` so consumers can choose between
     // the legacy single-line surface and the multi-line hint without re-
     // computing the spec.
-    hint: formatGateRequirementHint(gate),
+    hint: formatGateRequirementHint(gate, profile),
   };
 }
 
@@ -835,6 +946,35 @@ function parsePrReference(
     : { prNumber: second, componentPrNumber: first, ...repo };
 }
 
+/**
+ * Parse a `deploy:` payload, `<provider>/<deploymentId>@<sha>|<probe-url>`
+ * (T14083). The provider is lowercased, the SHA lowercased hex.
+ */
+function parseDeployPayload(payload: string, chunk: string): z.infer<typeof deployAtomSchema> {
+  const fix =
+    'Use format: deploy:<provider>/<deploymentId>@<sha>|<probe-url> e.g. ' +
+    'deploy:railway/9f3c2a@1a2b3c4d|https://api.example.com/health';
+  const bar = payload.indexOf('|');
+  const match = /^([^/]+)\/(.+)@([0-9A-Fa-f]{7,40})$/.exec(
+    bar < 0 ? '' : payload.slice(0, bar).trim(),
+  );
+  const probeUrl = bar < 0 ? '' : payload.slice(bar + 1).trim();
+  const parsed = deployAtomSchema.safeParse({
+    kind: 'deploy',
+    provider: match?.[1]?.toLowerCase() ?? '',
+    deploymentId: match?.[2] ?? '',
+    sha: match?.[3]?.toLowerCase() ?? '',
+    probeUrl,
+  });
+  if (!match || !parsed.success) {
+    throw new EvidenceParseError(
+      `Malformed deploy atom: "${chunk}" (${!match || parsed.success ? 'expected <provider>/<deploymentId>@<sha>|<probe-url>' : parsed.error.issues[0]?.message})`,
+      fix,
+    );
+  }
+  return parsed.data;
+}
+
 export function parseEvidenceString(raw: string): EvidenceAtom[] {
   if (!raw || typeof raw !== 'string') {
     throw new EvidenceParseError(
@@ -919,6 +1059,19 @@ export function parseEvidenceString(raw: string): EvidenceAtom[] {
         atoms.push(kind === 'pr' ? { kind: 'pr', ...ref } : { kind: 'ci', ...ref });
         break;
       }
+      case 'ci-run': {
+        if (!/^[1-9][0-9]*$/.test(payload)) {
+          throw new EvidenceParseError(
+            `ci-run atom requires a positive integer run id, got "${payload}" in "${chunk}"`,
+            'Use format: ci-run:<runId> e.g. ci-run:40812345678 (a repeat-run.yml run on main)',
+          );
+        }
+        atoms.push({ kind: 'ci-run', runId: Number(payload) });
+        break;
+      }
+      case 'deploy':
+        atoms.push(parseDeployPayload(payload, chunk));
+        break;
       case 'loc-drop': {
         const firstColon = payload.indexOf(':');
         if (firstColon < 1 || firstColon === payload.length - 1) {

package/src/exit-codes.ts

@@ -392,6 +392,47 @@ export const E_EVIDENCE_INSUFFICIENT = 'E_EVIDENCE_INSUFFICIENT' as const;
 export const E_PLAN_NOT_FOUND = 'E_PLAN_NOT_FOUND' as const;
 /** Generic release-plan validation failure (e.g. schema). Exit code 6. */
 export const E_RELEASE_PLAN_INVALID = 'E_RELEASE_PLAN_INVALID' as const;
+/**
+ * `cleo release cut` found no recent default-branch commit whose required `CI`
+ * check run concluded `success` (or the pinned `--sha` is not green). Exit code 6.
+ * `error.details.candidates[]` lists each commit checked and its CI state.
+ *
+ * @task T14102
+ */
+export const E_RELEASE_NO_GREEN_COMMIT = 'E_RELEASE_NO_GREEN_COMMIT' as const;
+/**
+ * `cleo release cut` found a changeset in range that no merged pull request
+ * brought in (pushed straight to the default branch). Exit code 6.
+ * `error.details.changesets[]` lists each file and the commit that added it.
+ *
+ * @task T14102
+ */
+export const E_RELEASE_UNMERGED_CHANGESET = 'E_RELEASE_UNMERGED_CHANGESET' as const;
+/**
+ * `cleo release cut` could not create the tag (the tag object or its ref POST
+ * failed). Exit code 1. `error.details.tagObject` names a created but
+ * unreferenced tag object, which is harmless. The attempt is audited.
+ *
+ * @task T14102
+ */
+export const E_RELEASE_TAG_FAILED = 'E_RELEASE_TAG_FAILED' as const;
+/**
+ * `cleo release cut --yes` from a non-interactive caller (an agent) without a
+ * standing release authorization (owner decision D11212; T14141 stores it).
+ * Exit code 6. A human at a terminal confirms with `--yes` directly.
+ *
+ * @task T14102
+ */
+export const E_RELEASE_NOT_AUTHORIZED = 'E_RELEASE_NOT_AUTHORIZED' as const;
+/**
+ * `cleo release cut` found docs rot (stale, duplicate or orphaned docs, per
+ * `cleo docs rot`) and refused to tag. Exit code 6. `error.details.docsRot`
+ * carries the scan.
+ *
+ * @task T14102
+ * @task T14111
+ */
+export const E_DOCS_ROT = 'E_DOCS_ROT' as const;
 /**
  * `cleo release plan` (or the lint script) encountered a `.changeset/*.md`
  * file whose YAML frontmatter cannot be parsed. Exit code 6 (VALIDATION_ERROR).

package/src/index.ts

@@ -422,6 +422,32 @@ export { CANONICAL_DOMAINS } from './dispatch/identity.js';
 export type { OperationDef, Resolution } from './dispatch/operation-def.js';
 // === Dispatch OPERATIONS data + builder helpers (T10061 — T9833b / E-CLI-BOUNDARY / SG-ARCH-SOLID) ===
 export { defineDomain, defineOp, OPERATIONS } from './dispatch/operations-registry.js';
+// === docs modernize plan + receipt (T14113) ===
+export type {
+  DocsModernizeDisposition,
+  DocsModernizeJudgment,
+  DocsModernizeJudgmentQuestion,
+  DocsModernizeJudgmentSource,
+  DocsModernizeLinkFix,
+  DocsModernizeOpKind,
+  DocsModernizeOpPrior,
+  DocsModernizeOpState,
+  DocsModernizeOverride,
+  DocsModernizeOverrides,
+  DocsModernizePlan,
+  DocsModernizePlanRow,
+  DocsModernizeReceipt,
+  DocsModernizeReceiptOp,
+  DocsModernizeStoreRow,
+} from './docs/modernize.js';
+export {
+  DOCS_MODERNIZE_DISPOSITIONS,
+  DOCS_MODERNIZE_OPS,
+  docsModernizeJournalLineSchema,
+  docsModernizeOverridesSchema,
+  docsModernizePlanSchema,
+  docsModernizeReceiptSchema,
+} from './docs/modernize.js';
 // === Docs Provenance Graph (T10166 / Saga T9855 / E12) ===
 export type {
   DocLifecycleStatus,
@@ -613,6 +639,7 @@ export type {
   EvidenceValidationFailure,
   EvidenceValidationResult,
   GateEvidenceRequirement,
+  GateProfileName,
 } from './evidence-atom-schema.js';
 export {
   AC_ALIAS_REGEX,
@@ -627,8 +654,10 @@ export {
   formatGateRequirement,
   formatGateRequirementHint,
   GATE_EVIDENCE_REQUIREMENTS,
+  GATE_PROFILE_NAMES,
   locDropAtomSchema,
   noteAtomSchema,
+  PROFILE_GATE_EVIDENCE,
   parseEvidenceString,
   prAtomSchema,
   qaRunAtomSchema,
@@ -1222,6 +1251,17 @@ export type {
   PatternRecord,
   SessionSummary,
 } from './memory.js';
+export type {
+  MacosRegressionSync,
+  MergeDirective,
+  MergePrOutcome,
+  MergeReceipt,
+  MergeSweepHooks,
+  MergeSweepOptions,
+  MergeSweepReconcile,
+  MergeSweepResult,
+  MergeTaskOutcome,
+} from './merge-close.js';
 export type {
   MigrationEnumDrift,
   MigrationForeignKeyViolation,
@@ -2094,6 +2134,9 @@ export type {
   ListWorktreesOptions,
   ListWorktreesOpts,
   ListWorktreesResult,
+  MergedCleanupItem,
+  MergedCleanupOpts,
+  MergedCleanupResult,
   PrunedWorktreeOutcome,
   PruneOrphanedWorktreesOpts,
   PruneOrphanedWorktreesResult,
@@ -2199,6 +2242,7 @@ export { PS_STABLE_ENV } from './process-probe.js';
 // === Project Context (ecosystem detection types) ===
 export type {
   EcosystemHint,
+  EvidenceRepositoryDeclaration,
   FileNamingConvention,
   ImportStyle,
   ProjectContext,
@@ -2653,6 +2697,7 @@ export type {
   EvidenceValidationContext,
   FileMeta,
   GateEvidence,
+  GateStandIn,
   Phase,
   PhaseStatus,
   PhaseTransition,
@@ -3275,6 +3320,16 @@ export {
   nexusStreamHeadSchema,
   nexusUserKeysSchema,
 } from './nexus-vault.js';
+// === Independent per-AC PR review (T14122) ===
+export type {
+  ReviewAnswer,
+  ReviewAuthors,
+  ReviewGap,
+  ReviewJudgement,
+  ReviewPacket,
+  ReviewPacketCriterion,
+  ReviewVerdict,
+} from './review-verdict.js';
 // === Sync schema version, shared by the change journal and the cloud vault (T13034) ===
 export { SYNC_SCHEMA_VERSION } from './sync-schema.js';
 export { isStorableTaskId, isTaskId, TASK_ID_REGEX, type TaskId } from './task-id.js';

package/src/invariants/sync-write-invariants.ts

@@ -558,6 +558,22 @@ export const SYNC_WRITE_INVARIANTS: readonly SyncWriteInvariant[] = Object.freez
     reason:
       'two devices adopting one legacy doc must mint one uid: the shell takes the legacy birth and sentinel facts, so (uid, birth_fp) converge and receive places the peer copy as a duplicate; a lost local write is refused loudly at the writer',
   },
+  // T14118 — a slug is an alias, not an identity: renaming one moves the
+  // live slug on the registry row and the conduit identity row together and
+  // records the old slug in the append-only alias table.
+  {
+    id: 'docs.slug.rename-keeps-alias',
+    class: 'identity-layer',
+    tables: [
+      'docs_attachments',
+      'conduit_attachments',
+      'docs_wikilinks',
+      'conduit_doc_slug_aliases',
+    ],
+    sites: [],
+    reason:
+      'a rename moves the live slug on docs_attachments and conduit_attachments in one transaction and records the old slug as an alias of the immutable doc uid, so every replica resolves the old and the new slug to one doc',
+  },
   // T13359 (D11165) — decisions-vs-ADRs link table; the natural composite key
   // makes identical links merge to one row, and the revoke is a one-way latch.
   // T13597: enforced at merge, not just by the local accessor — 'revoked' is an

package/src/memory/search.ts

@@ -74,6 +74,11 @@ export interface BrainCompactHit {
   _next?: Record<string, string>;
   /** Store the hit came from; absent means the project store (T13720). */
   scope?: MemoryScope;
+  /**
+   * Current docs linked to this decision (`docs link-decision`), each resolved
+   * past any supersession; never a superseded doc (T14110).
+   */
+  docs?: string[];
 }
 
 // ── SearchBrainCompactParams ────────────────────────────────────────
@@ -158,4 +163,9 @@ export interface SearchBrainCompactResult {
   total: number;
   /** Approximate token cost of the returned payload (~chars/4). */
   tokensEstimated: number;
+  /**
+   * For each task the query names (or a decision hit's task), the task's
+   * current docs; superseded docs are replaced by their current doc (T14110).
+   */
+  taskDocs?: Array<{ taskId: string; docs: string[] }>;
 }

package/src/merge-close.ts

@@ -0,0 +1,168 @@
+/**
+ * Merge closes tasks (T14101, owner decision D11209): the contract of the
+ * post-merge sweep that records a merged PR's evidence on the tasks its body
+ * names and completes them, with no agent step.
+ *
+ * A PR body names tasks one per line:
+ *
+ * - `Closes: T#### AC1,AC2` binds those criteria and completes the task once
+ *   the criteria every merged PR bound cover all of the task's criteria.
+ * - `Refs: T#### AC1` binds those criteria from a PR that delivers part of a
+ *   task, and leaves it open.
+ *
+ * @task T14101
+ */
+
+import type { MergedCleanupResult } from './operations/worktree.js';
+
+/** One `Closes:` / `Refs:` line of a PR body. */
+export interface MergeDirective {
+  /** `closes` completes the task; `refs` only binds criteria. */
+  kind: 'closes' | 'refs';
+  /** The task the line names. */
+  taskId: string;
+  /** Criterion aliases (`AC1`, …) the PR delivers, in the order written. */
+  acs: string[];
+}
+
+/**
+ * What a merged PR says, judged without a task store (the CI job's receipt):
+ * its lines, whether its required checks were green on its exact head, and
+ * why it closes nothing when it does not.
+ */
+export interface MergeReceipt {
+  /** PR number. */
+  prNumber: number;
+  /** The merge commit, or null when GitHub reports none. */
+  mergeSha: string | null;
+  /** The PR's final head. */
+  headSha: string | null;
+  /** The parsed lines. */
+  directives: MergeDirective[];
+  /** Malformed `Closes:` / `Refs:` lines, each with the fix. */
+  errors: string[];
+  /** Whether every required check passed on the PR's head. */
+  ciGreen: boolean;
+  /** Why CI does not count as green, when it does not. */
+  ciReason?: string;
+  /** Why the PR closes nothing at all, when it closes nothing. */
+  closesNothing?: string;
+}
+
+/** What the sweep did, or would do under `dryRun`, for one task of one PR. */
+export interface MergeTaskOutcome {
+  /** The task. */
+  taskId: string;
+  /**
+   * `closed`: evidence recorded and the task completed. `bound`: a `Refs:`
+   * line's criteria recorded, the task left open. `already`: an earlier sweep
+   * handled this PR for the task, or the task was already done. `refused`:
+   * nothing recorded; `reason` says why. `waiting`: the merge commit's own CI
+   * run was cancelled, skipped or has not finished and nothing stands in yet;
+   * the PR is re-judged every sweep.
+   */
+  action: 'closed' | 'bound' | 'already' | 'refused' | 'waiting';
+  /** The criteria the line named. */
+  acs: string[];
+  /** Why, for `refused` and `already`; for a dry run of an open PR, what would happen. */
+  reason?: string;
+}
+
+/** The sweep's result for one merged PR. */
+export interface MergePrOutcome {
+  /** PR number. */
+  prNumber: number;
+  /** Its merge commit. */
+  mergeSha: string | null;
+  /** One entry per task the PR names. */
+  outcomes: MergeTaskOutcome[];
+  /** Why nothing was attempted for this PR (no lines, malformed lines, CI not green). */
+  closesNothing?: string;
+}
+
+/** Options of `sweepMergedClosures`. */
+export interface MergeSweepOptions {
+  /** Report what would be recorded; write, complete and comment nothing. */
+  dryRun?: boolean;
+  /** Ignore the throttle (`cleo release` always passes it). */
+  force?: boolean;
+  /** Only PRs merged at or after this ISO time (default: the last sweep's high-water mark). */
+  since?: string;
+  /** Only these PRs (implies `force`). */
+  prNumbers?: number[];
+}
+
+/** What the sweep did with open `macos-regression` issues (T14104). */
+export interface MacosRegressionSync {
+  /** Tasks created for newly seen issues (under `dryRun`: issue URLs that would get one). */
+  created: string[];
+  /** Issue URLs closed because their task is done. */
+  closedIssues: string[];
+  /** Why the issues were not read. */
+  skippedReason?: string;
+}
+
+/** The newest release's provenance reconcile, run by the sweep (T14102). */
+export interface MergeSweepReconcile {
+  /** The release version, or null when there is none. */
+  version: string | null;
+  /** What happened. */
+  action: 'reconciled' | 'already' | 'unpublished' | 'none' | 'failed';
+  /** Why, when it did not reconcile. */
+  reason?: string;
+}
+
+/** The other upkeep one sweep runs after the closures, inside the same claim. */
+export interface MergeSweepHooks {
+  /** Task ids flagged `docs-update` for docs a merged change left stale (T14111). */
+  docsRot?: string[];
+  /** `macos-regression` issues turned into tasks, and closed when their task is done (T14104). */
+  macosRegression?: MacosRegressionSync;
+  /** The newest release's reconcile (T14102); skipped under `dryRun`. */
+  reconcile?: MergeSweepReconcile;
+  /**
+   * Worktrees, branches and nested copies merged work left behind, removed
+   * per applied PR (T14142). Off unless `CLEO_MERGE_SWEEP_CLEANUP=1`.
+   */
+  cleanup?: MergedCleanupResult[];
+}
+
+/** Result of `sweepMergedClosures` / `cleo done --from-merge`. */
+export interface MergeSweepResult {
+  /** False when the sweep did not run: throttled, `gh` unavailable, or offline. */
+  swept: boolean;
+  /** Why it did not run. */
+  skippedReason?: string;
+  /** Whether this was a dry run. */
+  dryRun: boolean;
+  /** Each merged PR considered, oldest merge first. */
+  prs: MergePrOutcome[];
+  /** Tasks completed (under `dryRun`: that would be). */
+  closed: string[];
+  /** Tasks with criteria bound by `Refs:`, left open. */
+  bound: string[];
+  /** Tasks nothing was recorded for, with the reason. */
+  refused: Array<{ taskId: string; prNumber: number; reason: string }>;
+  /** Task outcomes waiting on their merge commit's CI (re-judged every sweep). */
+  waiting: number;
+  /** Cancelled or skipped merge-commit CI runs this sweep reran (once per merge commit, ever). */
+  reran: number;
+  /**
+   * Set when more PRs merged than one sweep's page budget reads: `read` PRs
+   * were processed, and those merged in `[unreadSince, unreadBefore]` are read
+   * first by the next sweep (never skipped).
+   */
+  truncated?: { read: number; unreadSince: string; unreadBefore: string };
+  /**
+   * The pre-merge check of open PRs carrying Closes:/Refs: lines (T14122):
+   * the `cleo/merge-close` status each head got, and why when it failed.
+   */
+  openChecks?: Array<{
+    prNumber: number;
+    headSha: string;
+    state: 'success' | 'failure';
+    description: string;
+  }>;
+  /** The upkeep run in the same sweep, when any ran. */
+  hooks?: MergeSweepHooks;
+}