@cleocode/contracts 2026.10.27 → 2026.11.1-canary.2

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,31 @@ 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,
+  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,
@@ -1222,6 +1247,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 +2130,9 @@ export type {
   ListWorktreesOptions,
   ListWorktreesOpts,
   ListWorktreesResult,
+  MergedCleanupItem,
+  MergedCleanupOpts,
+  MergedCleanupResult,
   PrunedWorktreeOutcome,
   PruneOrphanedWorktreesOpts,
   PruneOrphanedWorktreesResult,
@@ -2199,6 +2238,7 @@ export { PS_STABLE_ENV } from './process-probe.js';
 // === Project Context (ecosystem detection types) ===
 export type {
   EcosystemHint,
+  EvidenceRepositoryDeclaration,
   FileNamingConvention,
   ImportStyle,
   ProjectContext,
@@ -2653,6 +2693,7 @@ export type {
   EvidenceValidationContext,
   FileMeta,
   GateEvidence,
+  GateStandIn,
   Phase,
   PhaseStatus,
   PhaseTransition,
@@ -3275,6 +3316,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;
+}

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. */
@@ -1121,7 +1166,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,7 +1210,7 @@ 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[];
@@ -1242,6 +1288,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 +1396,54 @@ 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;
+  /** 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 +1510,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;
+}