@cleocode/contracts 2026.10.27 → 2026.11.1-canary.3

package/src/operations/admin.ts

@@ -1662,6 +1662,12 @@ export interface AdminBackupMutateParams {
   confirmOwnerStore?: boolean;
   /** Create: also back up the global store (`<CLEO_HOME>/cleo.db`, T13245). */
   includeGlobal?: boolean;
+  /**
+   * Create: write the backup into this directory (the global copy under
+   * `<destination>/global`) instead of the rotating backup dirs; it never
+   * rotates or is rotated (T13209).
+   */
+  destination?: string;
   /** Restore by id: `global` restores a backup of the global store (T13245). */
   scope?: 'project' | 'global';
 }

package/src/operations/docs.ts

@@ -32,6 +32,8 @@
 
 import { z } from 'zod';
 import type { AttachmentKind } from '../attachment.js';
+import type { TaskPopulation } from '../data-accessor.js';
+import type { DocsModernizePlan, DocsModernizeReceipt } from '../docs/modernize.js';
 import { BUILTIN_DOC_KIND_VALUES, type BuiltinDocKind } from '../docs-taxonomy.js';
 import type {
   BackgroundJobStatus,
@@ -316,6 +318,12 @@ export interface DocsListResult {
    * @task T9792
    */
   totalCount?: number;
+  /**
+   * How many attachments matched, how many this response returns, whether it
+   * left any out, and the window applied (`null`: every match, `--limit 0`).
+   * The same shape `cleo list` reports (T14115).
+   */
+  population: Pick<TaskPopulation, 'matched' | 'returned' | 'truncated' | 'limit'>;
   /**
    * Effective limit applied to this response. Mirrored from the request
    * (or {@link DOCS_LIST_DEFAULT_LIMIT} when the request did not set one)
@@ -458,6 +466,37 @@ export interface DocsFetchResult {
    * ratifies.
    */
   linkedDecisions?: string[];
+  /**
+   * Where this doc sits in its supersession chain and what it serves
+   * (T14110). Present for slugged docs.
+   */
+  lineage?: DocsLineage;
+}
+
+/**
+ * A doc's supersession chain and the work it serves (T14110). Built from the
+ * existing `supersedes`/`superseded_by` pointers, task refs and
+ * `related_tasks`; nothing here is stored separately.
+ */
+export interface DocsLineage {
+  /** The doc's lifecycle status (`superseded` when replaced). */
+  readonly lifecycleStatus: string;
+  /** Slug of the doc this one replaced, when any. */
+  readonly supersedes: string | null;
+  /** Slug of the doc that replaced this one, when any. */
+  readonly supersededBy: string | null;
+  /**
+   * Slug of the current doc at the end of the `superseded_by` chain: this
+   * doc's own slug when it is current. Read this one instead.
+   */
+  readonly currentSlug: string;
+  /** Task ids the doc serves: its task owners and the tasks its body names. */
+  readonly servesTasks: readonly string[];
+  /**
+   * Decisions this doc supersedes: the `supersedes` of each decision it links
+   * (`docs link-decision`). Absent when it links none that supersede another.
+   */
+  readonly supersedesDecisions?: readonly string[];
 }
 
 // --------------------------------------------------------------------------
@@ -570,6 +609,12 @@ export interface DocsAddParams {
    * @saga T9855
    */
   strict?: boolean;
+  /**
+   * Why this doc is new although it resembles an existing one (T14109). A
+   * likely duplicate is refused unless this states the reason (at least 15
+   * characters); the reason is recorded in `.cleo/audit/docs-new-because.jsonl`.
+   */
+  newBecause?: string;
 }
 
 /** Canonical attachment and owner whose optional projections may be prepared. */
@@ -1104,6 +1149,12 @@ export interface DocsDoctorParams {
   repair?: boolean;
   /** Age threshold (days) for the `stale-drafts` diagnostic. Default 30. */
   olderThanDays?: number;
+  /**
+   * Comma-separated repair classes to scope the run to (T14174), for example
+   * `publication-ledger-drift`. Only their repairs are planned and, with
+   * `apply`, written. Diagnostics still cover every class.
+   */
+  only?: string;
 }
 
 /**
@@ -1121,7 +1172,8 @@ export interface DocsDoctorDiagnostic {
     | 'legacy-store-present'
     | 'legacy-blob-coverage'
     | 'stale-drafts'
-    | 'conduit-history-gaps';
+    | 'conduit-history-gaps'
+    | 'publication-ledger-drift';
   /** `error` should be fixed promptly; `info` is observational. */
   severity: 'info' | 'warn' | 'error';
   /** Total offenders found (may exceed `items.length`). */
@@ -1164,10 +1216,18 @@ export interface DocsDoctorResult {
   olderThanDays: number;
   /** Backup receipt that authorised this run (null on dry runs). */
   backupReceiptPath: string | null;
-  /** All eight diagnostics, in declaration order. */
+  /** All nine diagnostics, in declaration order. */
   diagnostics: readonly DocsDoctorDiagnostic[];
   /** Repair plan (dry run) or executed repairs (apply). */
   repairs: readonly DocsDoctorRepairAction[];
+  /** Repairs per class: planned entries and those written (T14174). */
+  repairCounts: Readonly<
+    Partial<
+      Record<DocsDoctorDiagnostic['kind'], { readonly planned: number; readonly applied: number }>
+    >
+  >;
+  /** The repair classes this run was scoped to, or null for every class (T14174). */
+  only: readonly DocsDoctorDiagnostic['kind'][] | null;
   /** One-line human summary. */
   summary: string;
 }
@@ -1242,6 +1302,87 @@ export interface DocsStatsResult {
   readonly summary: string;
 }
 
+/**
+ * Parameters for `docs.rot` — the docs-rot report (T14111).
+ *
+ * Read-only and git-only: it reads tracked markdown and git history, never
+ * the docs store, so it runs the same in CI and locally.
+ *
+ * @task T14111 (Epic T14106)
+ */
+export interface DocsRotParams {
+  /**
+   * Git revision range `<base>..<head>` of a merged change. When set, the
+   * report also lists the docs whose `covers:` globs match a file the range
+   * changed (and that the range did not update itself).
+   */
+  readonly changed?: string;
+}
+
+/**
+ * A doc whose declared `covers:` code changed without the doc changing.
+ *
+ * @task T14111
+ */
+export interface DocsRotCoverageHit {
+  /** Repo-relative path of the doc. */
+  readonly doc: string;
+  /** Covered files that changed (sorted, repo-relative). */
+  readonly files: readonly string[];
+}
+
+/**
+ * A group of docs that duplicate each other: identical bodies, or titles
+ * close enough that one is a fork of the other.
+ *
+ * @task T14111
+ */
+export interface DocsRotDuplicate {
+  /** Why the docs were grouped: `content` (same body) or `title`. */
+  readonly reason: 'content' | 'title';
+  /** Repo-relative paths of the duplicates (sorted). */
+  readonly docs: readonly string[];
+}
+
+/**
+ * A doc nothing ties to the repo: a `covers:` glob that matches no tracked
+ * file, or a `docs/` file no other tracked file references.
+ *
+ * @task T14111
+ */
+export interface DocsRotOrphan {
+  /** Repo-relative path of the doc. */
+  readonly doc: string;
+  /** `dead-covers` (globs listed in `globs`) or `unreferenced`. */
+  readonly reason: 'dead-covers' | 'unreferenced';
+  /** The covers globs that match nothing (only for `dead-covers`). */
+  readonly globs?: readonly string[];
+}
+
+/**
+ * Result of `docs.rot` — stale, duplicate and orphaned docs (T14111).
+ *
+ * @task T14111
+ */
+export interface DocsRotResult {
+  /** Tracked markdown docs scanned. */
+  readonly scanned: number;
+  /** Docs that declare `covers:`. */
+  readonly covering: number;
+  /** Docs whose covered code changed after the doc last changed on main. */
+  readonly stale: readonly DocsRotCoverageHit[];
+  /** Duplicate doc groups. */
+  readonly duplicates: readonly DocsRotDuplicate[];
+  /** Orphaned docs. */
+  readonly orphans: readonly DocsRotOrphan[];
+  /** Docs the `changed` range flags for update (empty without `changed`). */
+  readonly flagged: readonly DocsRotCoverageHit[];
+  /** Wall time of the scan in milliseconds. */
+  readonly durationMs: number;
+  /** One-line human summary. */
+  readonly summary: string;
+}
+
 // ============================================================================
 // Discriminated Union (DocsOps)
 // ============================================================================
@@ -1269,7 +1410,59 @@ export type DocsOps =
   | { op: 'docs.unlink-decision'; params: DocsDecisionLinkParams; result: DocsDecisionLinkResult }
   | { op: 'docs.doctor'; params: DocsDoctorParams; result: DocsDoctorResult }
   | { op: 'docs.migrate'; params: DocsMigrateParams; result: DocsMigrateResult }
-  | { op: 'docs.stats'; params: DocsStatsParams; result: DocsStatsResult };
+  | { op: 'docs.modernize'; params: DocsModernizeParams; result: DocsModernizeResult }
+  | { op: 'docs.stats'; params: DocsStatsParams; result: DocsStatsResult }
+  | { op: 'docs.rot'; params: DocsRotParams; result: DocsRotResult };
+
+/**
+ * Parameters for `docs.modernize` (T14113) — dry run by default.
+ */
+export interface DocsModernizeParams {
+  /** Folder to modernize, relative to the project root or absolute. Required unless `rollback`. */
+  readonly path?: string;
+  /** Execute the plan; without it the run is a dry run that writes nothing. */
+  readonly apply?: boolean;
+  /** Apply this saved plan JSON verbatim instead of re-planning. */
+  readonly planFile?: string;
+  /** Save the plan JSON here. */
+  readonly out?: string;
+  /** Roll back the apply run with this id. */
+  readonly rollback?: string;
+  /** Extra folder names to skip, comma-separated. */
+  readonly exclude?: string;
+  /** Path of a `DocsModernizeOverrides` JSON file keyed by root-relative path. */
+  readonly overrides?: string;
+  /** Use this kind for every file instead of classifying. */
+  readonly kind?: string;
+  /** Ingest every file into the store (task-owned, slugless) and leave the folder untouched. */
+  readonly storeOnly?: boolean;
+  /** Apply even when the root is not a clean git checkout. */
+  readonly allowDirty?: boolean;
+  /**
+   * Rewrite relative links to planned docs as `[[slug]]` wikilinks (opt-in).
+   * By default links stay markdown, re-pointed at the new paths (T14185).
+   */
+  readonly wikilinks?: boolean;
+  /** Modernize the docs already in the store (re-kind, re-slug with aliases, ADR numbers). */
+  readonly store?: boolean;
+}
+
+/**
+ * Result of `docs.modernize`: the plan (dry run, apply) and the receipt
+ * (apply, rollback).
+ */
+export interface DocsModernizeResult {
+  /** What ran. */
+  readonly mode: 'dry-run' | 'apply' | 'rollback';
+  /** The plan, or null for a rollback. */
+  readonly plan: DocsModernizePlan | null;
+  /** Where the plan was saved, when `out` was given. */
+  readonly planPath: string | null;
+  /** The receipt, or null for a dry run. */
+  readonly receipt: DocsModernizeReceipt | null;
+  /** One-line human summary. */
+  readonly summary: string;
+}
 
 /**
  * Parameters for `docs.migrate` — the T13360 legacy docs migration (spec §5).
@@ -1336,4 +1529,6 @@ export type DocsOp =
   | 'docs.unlink-decision'
   | 'docs.doctor'
   | 'docs.migrate'
-  | 'docs.stats';
+  | 'docs.modernize'
+  | 'docs.stats'
+  | 'docs.rot';

package/src/operations/worktree.ts

@@ -1098,3 +1098,69 @@ export interface AdoptWorktreeResult {
    */
   projectInfo: 'seeded' | 'present' | 'skipped';
 }
+
+/**
+ * Options for `cleanupMergedWork` (T14142): remove what merged work left
+ * behind, after proving each item redundant.
+ *
+ * @task T14142
+ */
+export interface MergedCleanupOpts {
+  /** Project root (the main checkout; its hash names the canonical worktree root). */
+  projectRoot: string;
+  /**
+   * Tasks whose work merged (the sweep's merged PR, or a release's tasks).
+   * Either way a task is in scope only while stored `done` or `cancelled`:
+   * an open task (more PRs to come) keeps its worktree and branches.
+   */
+  taskIds?: readonly string[];
+  /** List everything without deleting. Default `true`: deleting is opt-in. */
+  dryRun?: boolean;
+  /** Also delete merged task branches on `origin`. Default `true`. */
+  remote?: boolean;
+}
+
+/**
+ * One item the cleanup considered: removed (or, on a dry run, removable), or
+ * kept with the reason.
+ *
+ * @task T14142
+ */
+export interface MergedCleanupItem {
+  /** Worktree or nested-copy path, or branch name. */
+  target: string;
+  /** Owning task, when the target names one. */
+  taskId: string | null;
+  /** Branch tip (branches only): what a restore pushes back. */
+  sha?: string;
+  /** True when removed (dry run: when it would be removed). */
+  removed: boolean;
+  /** Why it was kept, or what proved it redundant. */
+  reason: string;
+  /** Bytes on disk (worktrees and nested copies; 0 for branches). */
+  bytes: number;
+}
+
+/**
+ * Result of `cleanupMergedWork` (T14142).
+ *
+ * @task T14142
+ */
+export interface MergedCleanupResult {
+  /** Whether nothing was deleted. */
+  dryRun: boolean;
+  /** The default branch merges were proven against (`origin/<name>`). */
+  base: string;
+  /** Canonical task worktrees. */
+  worktrees: MergedCleanupItem[];
+  /** Local `task/*` branches. */
+  localBranches: MergedCleanupItem[];
+  /** `origin` `task/*` branches. */
+  remoteBranches: MergedCleanupItem[];
+  /** Repository copies nested inside worktrees. */
+  nestedCopies: MergedCleanupItem[];
+  /** Bytes removed (dry run: that would be removed). */
+  bytesReclaimed: number;
+  /** Why nothing was considered (the fetch failed, no base branch); absent when it ran. */
+  skippedReason?: string;
+}

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;
 }
 
 /**