@cleocode/contracts 2026.10.18 → 2026.10.19

package/src/branch-lock.ts

@@ -294,6 +294,12 @@ export interface OwnerOverrideAuditRecord {
   reason: string;
   /** Process ID. */
   pid: number;
+  /** The owner setting a set or refused set targeted (T13787). */
+  setting?: string;
+  /** The setting's value before the attempt (T13787). */
+  old_value?: number;
+  /** The value the attempt asked for, or set (T13787). */
+  new_value?: number;
 }
 
 /**
@@ -340,9 +346,14 @@ export const BRANCH_LOCK_ERROR_CODES = {
   /** L4d: session override limit exceeded. */
   E_OVERRIDE_RATE_LIMIT: 'E_OVERRIDE_RATE_LIMIT',
   /**
-   * T1501 / P0-5: per-session cap (default 3) exceeded without a valid waiver doc.
-   * Set CLEO_OWNER_OVERRIDE_WAIVER=<absolute path> to a file containing
-   * `cap-waiver: true` in its frontmatter to bypass the cap.
+   * T13790: CLEO_OWNER_OVERRIDE from a caller that is not the owner — no
+   * owner-marked session (`cleo session start … --owner-auth`), or not on the
+   * owner's own terminal.
+   */
+  E_OVERRIDE_NOT_OWNER: 'E_OVERRIDE_NOT_OWNER',
+  /**
+   * T1501 / P0-5: per-session cap exceeded. The cap is the owner's sealed
+   * `evidence.overrideCapPerSession` (default 10, T13787); no waiver lifts it.
    */
   E_OVERRIDE_CAP_EXCEEDED: 'E_OVERRIDE_CAP_EXCEEDED',
   /**

package/src/dispatch/operations-registry.ts

@@ -9705,6 +9705,14 @@ export const OPERATIONS: OperationDef[] = [
         description:
           'Comma-separated task IDs forwarded as the plan scope for a task-scoped release',
       },
+      // T13825: the single release PR's plan branch.
+      {
+        name: 'ref',
+        type: 'string',
+        required: false,
+        description:
+          'Branch to dispatch release-prepare on (release/plan-<version>: the plan + CHANGELOG commit on top of the default branch), so the bump PR carries the plan too',
+      },
     ] satisfies ParamDef[],
   },
 

package/src/done-plan.ts

@@ -89,6 +89,8 @@ export interface DonePlanBlocker {
   next: DoneNextStep;
   /** Original evidence error code when the blocker wraps a validator refusal. */
   cause?: string;
+  /** The verification gate the blocker holds back, when it is one gate's (T13795). */
+  gate?: VerificationGate;
 }
 
 /** A merged PR that cites the task. */
@@ -373,3 +375,74 @@ export interface DoneBlockedDetails {
   /** The plan, for tooling. */
   plan: DonePlan;
 }
+
+/** A test file a covering test-run report must run, and why. */
+export interface OwedTestFile {
+  /** Repo-relative test file. */
+  file: string;
+  /** Why the binding requires it. */
+  reason: string;
+}
+
+/** An affected package a covering report must run at least one test file of. */
+export interface OwedTestPackage {
+  /** Workspace package name. */
+  name: string;
+  /** Changed itself, or depends on a changed package. */
+  reason: 'changed' | 'depends on a changed package';
+  /** Test files of this package the change adds or edits (the natural choice). */
+  changedTestFiles: string[];
+}
+
+/**
+ * The tests a task's change owes, as the `test-run:` binding and
+ * `cleo done --plan` enforce them (T13795).
+ *
+ * - `targeted`: a passing report of every `files` entry plus at least one test
+ *   file of every `packages` entry binds (config files and typecheck-only
+ *   dependents are owed their own results).
+ * - `full`: the change is workspace-wide; only `tool:test` (or `ci:<pr>`) binds.
+ * - `none`: no changed path to judge (no origin default branch, or no change).
+ */
+export interface TaskTestPlan {
+  /** Changed paths judged, or null when none could be read. */
+  changedPaths: string[] | null;
+  /** How the change can be tested. */
+  scope: 'targeted' | 'full' | 'none';
+  /** Why only a full run binds (`scope === 'full'`). */
+  reason?: string;
+  /** Exact test files a covering report must run. */
+  files: OwedTestFile[];
+  /** Packages a covering report must run at least one test file of. */
+  packages: OwedTestPackage[];
+  /** Affected packages with no test file at all. */
+  untestedPackages: string[];
+  /** CLEO config files the change edits, owed `tool:config-schema` instead of a test. */
+  configPaths: string[];
+  /** Typecheck-only dependent package dirs, owed a typecheck instead of a test. */
+  typecheckDirs: string[];
+  /**
+   * Whether the change has merged. A merged change is judged as `cleo complete`
+   * judges it: the task's own part of the landed change, and every test file it
+   * adds or edits owed by a test-run recorded on the default branch.
+   */
+  merged: boolean;
+  /** Whether the task already holds a standing testsPassed gate. */
+  gatePassed: boolean;
+  /** The testsPassed tool runs `cleo done` would use. */
+  toolRuns: DonePlanToolRun[];
+  /** The testsPassed blockers `cleo done --plan` reports. */
+  blockers: DonePlanBlocker[];
+}
+
+/** Result of `cleo tasks changeset <id> [--test-plan]` (T13795). */
+export interface TaskChangeSetReport {
+  /** Task id. */
+  taskId: string;
+  /** The change set `cleo done` derives. */
+  changeSet: TaskChangeSet;
+  /** Commits of the change, oldest first. */
+  commits: string[];
+  /** The tests owed (with `--test-plan`). */
+  testPlan?: TaskTestPlan;
+}

package/src/goal-contract.ts

@@ -2,7 +2,7 @@
  * goal/v1 — the contract a goal runtime executes against, and what CLEO reads
  * back from a run.
  *
- * CLEO owns the goal protocol; OpenCode-Goal (OCG) is the goal runtime (owner
+ * CLEO owns the goal protocol; CLEO Goal (`@cleocode/goal`, bin `cleo-goal`, alias `ocg`) is the goal runtime (owner
  * decision 2026-10-16, epic T13791). The two stay separate packages and talk
  * only through the `cleo` CLI and LAFS envelopes:
  *
@@ -13,7 +13,7 @@
  * 3. `cleo goal close` reads the outcome and records evidence for each passing
  *    criterion on the gate it demonstrates, via {@link GoalCriterion.proves}.
  *
- * The shapes mirror OCG's `src/contract/types.ts` field for field, in OCG's
+ * The shapes mirror CLEO Goal's `src/contract/types.ts` field for field, in CLEO Goal's
  * snake_case YAML spelling, so one file means the same thing on both sides.
  * The only addition is the optional per-criterion `proves` list.
  *
@@ -31,6 +31,8 @@
  * @task T13792
  */
 
+import type { GoalRuntimeStatus } from './goal-runtime.js';
+
 /** The schema tag every goal/v1 contract carries. */
 export const GOAL_CONTRACT_SCHEMA = 'goal/v1' as const;
 
@@ -243,9 +245,9 @@ export type GoalVerificationMode = 'host' | 'host+verifier' | 'strict';
 export type GoalCleoGate = 'implemented' | 'testsPassed' | 'qaPassed';
 
 /**
- * A CLEO task the goal serves (OCG `CleoTaskLink`).
+ * A CLEO task the goal serves (CLEO Goal `CleoTaskLink`).
  *
- * The bare id links the task for reporting. `acs` is OCG's older per-gate
+ * The bare id links the task for reporting. `acs` is CLEO Goal's older per-gate
  * claim of which AC aliases a gate's evidence proves; per-criterion
  * {@link GoalCriterion.proves} is the precise form and what `cleo goal draft`
  * writes. An AC neither form claims stays open.
@@ -436,3 +438,45 @@ export interface GoalOutcome {
   /** Per-criterion and per-invariant verdicts. */
   results: GoalCriterionOutcome[];
 }
+
+/** A drafted goal and the CLEO tasks it serves, from its `goal.yaml` (T13821). */
+export interface GoalDraftEntry {
+  /** Goal slug (its directory under `.opencode/goals/`). */
+  slug: string;
+  /** Contract title, when the contract parses. */
+  title: string | null;
+  /** CLEO tasks the goal serves: `cleo.tasks` plus every task a criterion proves. */
+  tasks: string[];
+  /** Why the contract could not be read, when it could not. */
+  problem?: string;
+}
+
+/**
+ * `cleo goal status` (T13821): the drafted goals and the live run, which CLEO
+ * reads only through `cleo-goal status --json`, never the runtime's files.
+ */
+export interface GoalStatusReport {
+  /** Whether the CLEO Goal bin (`cleo-goal`, alias `ocg`) is installed. */
+  runtime: 'installed' | 'not-installed';
+  /** The commands that install it, when it is not installed. */
+  install?: string[];
+  /** The live run, from `cleo-goal status --json`; null when not installed. */
+  live: GoalRuntimeStatus | null;
+  /** The drafted goals (filtered to one task with `--task`). */
+  goals: GoalDraftEntry[];
+}
+
+/**
+ * The goal runtime (CLEO Goal) as `cleo go` finds it, and the exact next step
+ * in the current harness (T13821).
+ */
+export interface GoalRuntimeHandoff {
+  /** Whether the CLEO Goal bin (`cleo-goal`, then `ocg`) resolves. */
+  installed: boolean;
+  /** The resolved bin, when installed. */
+  bin?: string;
+  /** The commands that install it, when it is not installed. */
+  install?: string[];
+  /** The one next step, in plain words. */
+  next: string;
+}

package/src/goal-runtime.ts

@@ -0,0 +1,105 @@
+/**
+ * Wire shapes of the CLEO Goal runtime bin (`@cleocode/goal`, bin `cleo-goal`,
+ * alias `ocg`) that CLEO parses. CLEO talks to the runtime only through these
+ * JSON outputs (T13791); an unknown `schemaVersion` is refused, never guessed.
+ *
+ * @task T13819
+ * @task T13820
+ * @task T13821
+ * @epic T13791
+ */
+
+/** The only `schemaVersion` this CLEO understands for every shape below. */
+export const GOAL_RUNTIME_SCHEMA_VERSION = 1;
+
+/** Run state reported by `cleo-goal status --json`; `none` when no goal is live. */
+export type GoalRuntimeRunStatus =
+  | 'running'
+  | 'waiting'
+  | 'verifying'
+  | 'paused'
+  | 'blocked'
+  | 'needs_review'
+  | 'budget_limited'
+  | 'complete'
+  | 'failed'
+  | 'aborted'
+  | 'superseded'
+  | 'none';
+
+/** One criterion of the live goal. */
+export interface GoalRuntimeCriterion {
+  readonly id: string;
+  readonly statement: string;
+  readonly status: string;
+  readonly essential: boolean;
+  readonly invariant: boolean;
+  readonly by: string;
+  readonly detail: string;
+}
+
+/** One budget dimension (turns, tokens, time, …). */
+export interface GoalRuntimeBudgetPart {
+  readonly name: string;
+  readonly used: number;
+  readonly limit: number;
+}
+
+/**
+ * `cleo-goal status --json` stdout. The bin exits 0 whenever the project was
+ * readable, including with no goal (`goal: null`, `status: 'none'`).
+ */
+export interface GoalRuntimeStatus {
+  readonly schemaVersion: typeof GOAL_RUNTIME_SCHEMA_VERSION;
+  readonly goal: string | null;
+  readonly runId: string | null;
+  readonly title: string;
+  readonly status: GoalRuntimeRunStatus;
+  readonly priority?: string;
+  readonly turn: number;
+  readonly reason: string | null;
+  readonly criteria: readonly GoalRuntimeCriterion[];
+  readonly proven: number;
+  readonly total: number;
+  readonly budget: { readonly ratio: number; readonly parts: readonly GoalRuntimeBudgetPart[] };
+  readonly verdict: {
+    readonly passed: boolean;
+    readonly lines: readonly string[];
+    readonly turn: number;
+  } | null;
+  readonly blocker: {
+    readonly key: string;
+    readonly count: number;
+    readonly reason: string;
+  } | null;
+  /** Epoch milliseconds. */
+  readonly updatedAt: number;
+}
+
+/**
+ * One OpenCode v2 `plugins` entry: a spec, a `[spec, options]` tuple, or a
+ * `{ package, options }` object.
+ */
+export type GoalRuntimePluginEntry =
+  | string
+  | readonly [string, Readonly<Record<string, unknown>>]
+  | { readonly package: string; readonly options?: Readonly<Record<string, unknown>> };
+
+/**
+ * `cleo-goal install --project --json` stdout on exit 0. Writes only the
+ * project's `.opencode/opencode.json` (OpenCode v2 `plugins` key).
+ */
+export interface GoalRuntimeInstall {
+  readonly schemaVersion: typeof GOAL_RUNTIME_SCHEMA_VERSION;
+  readonly action: 'installed' | 'already-present' | 'updated' | 'dry-run';
+  readonly file: string;
+  /** The npm or git spec registered (`github:…#vX.Y.Z` until npm publish). */
+  readonly spec: string;
+  readonly plugins: readonly GoalRuntimePluginEntry[];
+}
+
+/** `cleo-goal` stdout on exit 1 (exit 2 is a usage error on stderr only). */
+export interface GoalRuntimeError {
+  readonly schemaVersion: typeof GOAL_RUNTIME_SCHEMA_VERSION;
+  readonly error: string;
+}

package/src/goal.ts

@@ -1,38 +1,20 @@
 /**
- * CLEO-native goal-system contracts (Layer 4 of SG-COGNITIVE-SUBSTRATE).
+ * CLEO goal record contracts.
  *
- * A *goal* is a DB-persisted, per-agent, turn-budgeted intent that CLEO drives
- * to completion by judging progress after every agent turn. CLEO's goal loop is
- * designed to beat two prior-art systems:
- *
- * - **Claude-Code** — a `Stop` hook + a Haiku *transcript judge* (the model
- *   reads the conversation and guesses whether the task is done). It has no
- *   turn budget and no persistence: a fresh process forgets the goal.
- * - **Hermes** — a post-turn loop with a turn budget and parse-failure
- *   auto-pause, but it still judges *fuzzy* intent against transcript text.
- *
- * CLEO's differentiator is the **evidence-gate-aware judge**: when a goal is to
- * *complete a task* (`complete T123`), the judge does NOT read the transcript.
- * It resolves the target task's actual `status` and re-uses the shipped ADR-051
- * evidence infrastructure ({@link GateEvidenceRequirement} +
- * `validateEvidenceForGate`) — the goal is satisfied ONLY when the task is
- * `done` with its required gates backed by real, validated evidence atoms
- * (commit reachable, file sha256 match, test-run hash match). Transcript text
- * can never satisfy a task-completion goal. Fuzzy goals fall back to an
- * injectable LLM judge (see {@link GoalJudge}) so the model is consulted only
- * where no machine-checkable artifact exists.
- *
- * This module is the LEAF contract: it declares the persisted record shape
- * ({@link GoalRecord}), the lifecycle status union ({@link GoalStatus}), the
- * discriminated goal-kind union ({@link GoalKind}), and the judge verdict shape
- * ({@link GoalJudgeVerdict}) that every layer (store, judge, loop, continuation,
- * CLI) agrees on. It has ZERO runtime dependencies beyond sibling contracts.
+ * CLEO owns the goal protocol and CLEO Goal is the goal runtime (owner
+ * decision 2026-10-16, epic T13791, ADR-097 `adr-097-goal-protocol-ocg-runtime`). The
+ * protocol's portable shapes (goal/v1 contract, task link, outcome) live in
+ * `./goal-contract.ts`. This module keeps the DB-persisted per-agent goal
+ * record ({@link GoalRecord}) and its status and kind unions. CLEO's own
+ * turn-budgeted goal loop (judge, continuation builder, Stop-hook advance) was
+ * retired in T13797, with its judge and continuation contracts.
  *
  * @packageDocumentation
  * @module @cleocode/contracts/goal
  *
  * @epic T11290 EP-CLEO-GOAL-SYSTEM
  * @task T11376
+ * @task T13797
  * @saga T11283 SG-COGNITIVE-SUBSTRATE
  */
 
@@ -81,21 +63,6 @@ export const GOAL_STATUSES: readonly GoalStatus[] = Object.freeze([
   'impossible',
 ]);
 
-/**
- * The terminal {@link GoalStatus} values a continuation builder must NOT nudge:
- * a satisfied/abandoned/impossible goal yields no next-turn message.
- *
- * `paused` is intentionally absent — a paused goal CAN be resumed, so the
- * continuation builder still emits a nudge for it (see `buildContinuation`).
- *
- * @public
- */
-export const GOAL_TERMINAL_STATUSES: readonly GoalStatus[] = Object.freeze([
-  'satisfied',
-  'abandoned',
-  'impossible',
-]);
-
 /**
  * Discriminant tag for the {@link GoalKind} union.
  *
@@ -125,7 +92,7 @@ export interface TaskCompletionGoal {
 
 /**
  * A goal with no machine-checkable completion artifact — satisfaction is
- * decided by the injectable LLM judge ({@link GoalJudge}) as a fallback.
+ * decided by an LLM judge as a fallback.
  *
  * The fuzzy path NEVER touches the evidence infrastructure; it exists only for
  * intents that cannot be reduced to a task + gates (e.g. "explore the auth
@@ -207,8 +174,8 @@ export interface GoalRecord {
    */
   readonly pausedReason: string | null;
   /**
-   * The most recent judge verdict, persisted so `cleo goal status` can show the
-   * last reason without re-running the judge. `null` before the first judge.
+   * The most recent judge verdict, persisted with the record. `null` before
+   * the first judge.
    */
   readonly lastVerdict: GoalJudgeVerdict | null;
   /** ISO-8601 creation timestamp. */
@@ -248,82 +215,6 @@ export interface GoalJudgeVerdict {
   readonly evidence?: readonly string[];
 }
 
-/**
- * Injectable LLM-judge interface for {@link FuzzyGoal} evaluation.
- *
- * The goal judge depends on THIS interface, never on a concrete model client,
- * so vitest can pass a deterministic mock and stay fully offline/hermetic — CI
- * must never flake on a live model call. Production wires a real LLM-backed
- * implementation; tests wire a stub that returns a canned verdict.
- *
- * @public
- */
-export interface GoalJudge {
-  /**
-   * Judge a fuzzy goal from its record alone (no transcript dependency in the
-   * contract — an implementation MAY consult external context, but the
-   * interface keeps the judge a pure function of the goal for testability).
-   *
-   * @param goal - The goal record under evaluation.
-   * @returns The verdict (same shape as the evidence path).
-   */
-  judge(goal: GoalRecord): Promise<GoalJudgeVerdict>;
-}
-
-/**
- * A single next-turn continuation message produced by the cache-safe builder.
- *
- * Critically, the role is ALWAYS `'user'`: the goal loop nudges the agent by
- * appending a user-style message, NEVER by mutating the system prompt. A stable
- * system-prompt prefix is what makes prompt-caching effective; rewriting it on
- * every turn would bust the cache. See `buildContinuation` for the full
- * prompt-cache-safety contract.
- *
- * @public
- */
-export interface GoalContinuation {
-  /** Always `'user'` — the nudge is a user message, never a system mutation. */
-  readonly role: 'user';
-  /** The continuation text: goal intent + outstanding criteria + judge reason. */
-  readonly content: string;
-}
-
-/**
- * Result of advancing a goal one turn through the turn-budgeted loop.
- *
- * @public
- */
-export interface GoalAdvanceResult {
-  /** The verdict the judge returned this turn. */
-  readonly verdict: GoalJudgeVerdict;
-  /** The status the goal transitions to after this turn. */
-  readonly nextStatus: GoalStatus;
-  /** Turns left after this one. Never negative. */
-  readonly turnsRemaining: number;
-}
-
-/**
- * Type guard: is this a {@link TaskCompletionGoal} (evidence-judged)?
- *
- * @param kind - A {@link GoalKind} discriminated union value.
- * @returns `true` when the goal is judged via task status + evidence atoms.
- * @public
- */
-export function isTaskCompletionGoal(kind: GoalKind): kind is TaskCompletionGoal {
-  return kind.kind === 'task-completion';
-}
-
-/**
- * Type guard: is this a {@link FuzzyGoal} (LLM-judged fallback)?
- *
- * @param kind - A {@link GoalKind} discriminated union value.
- * @returns `true` when the goal is judged by the injectable LLM judge.
- * @public
- */
-export function isFuzzyGoal(kind: GoalKind): kind is FuzzyGoal {
-  return kind.kind === 'fuzzy';
-}
-
 /**
  * Test whether a string is a valid goal target task id (`T` + 1–7 digits).
  *
@@ -334,15 +225,3 @@ export function isFuzzyGoal(kind: GoalKind): kind is FuzzyGoal {
 export function isValidGoalTargetTaskId(value: string): boolean {
   return GOAL_TARGET_TASK_ID_REGEX.test(value);
 }
-
-/**
- * Test whether a {@link GoalStatus} is terminal (no further turns / nudges that
- * advance work). A terminal status yields NO continuation.
- *
- * @param status - A goal status.
- * @returns `true` for `satisfied` / `abandoned` / `impossible`.
- * @public
- */
-export function isTerminalGoalStatus(status: GoalStatus): boolean {
-  return GOAL_TERMINAL_STATUSES.includes(status);
-}

package/src/heavy-command-hook.ts

@@ -303,4 +303,13 @@ export interface HeavyHookDeliveryApi {
     projectDir: string,
     options?: HeavyHookDeliveryOptions,
   ) => HeavyHookCliProbe;
+  /**
+   * Install only the Stop dispatcher (`cleo hook stop`) for one provider,
+   * regardless of the heavy-command mode (T13820). Optional: an older
+   * adapters build lacks it. Never throws.
+   */
+  readonly syncProjectStopDispatch?: (
+    projectDir: string,
+    provider: 'claude-code' | 'codex',
+  ) => Promise<HeavyHookDeliveryOutcome>;
 }

package/src/index.ts

@@ -551,7 +551,11 @@ export type {
   DonePlanTypedGate,
   DoneRecordResult,
   DoneToolResult,
+  OwedTestFile,
+  OwedTestPackage,
   TaskChangeSet,
+  TaskChangeSetReport,
+  TaskTestPlan,
 } from './done-plan.js';
 export type {
   EngineErrorPayload,
@@ -730,9 +734,6 @@ export {
 // === CLEO-native Goal System (T11376 · Epic T11290 · Saga T11283) ===
 export type {
   FuzzyGoal,
-  GoalAdvanceResult,
-  GoalContinuation,
-  GoalJudge,
   GoalJudgeVerdict,
   GoalKind,
   GoalKindTag,
@@ -743,10 +744,6 @@ export type {
 export {
   GOAL_STATUSES,
   GOAL_TARGET_TASK_ID_REGEX,
-  GOAL_TERMINAL_STATUSES,
-  isFuzzyGoal,
-  isTaskCompletionGoal,
-  isTerminalGoalStatus,
   isValidGoalTargetTaskId,
 } from './goal.js';
 // === goal/v1 protocol: contract, task link, outcome (T13792 · Epic T13791) ===
@@ -769,12 +766,15 @@ export type {
   GoalCriterion,
   GoalCriterionOutcome,
   GoalDiffCheck,
+  GoalDraftEntry,
   GoalFileCheck,
   GoalHumanCheck,
   GoalHumanEvidence,
   GoalOutcome,
   GoalPathEvidence,
   GoalPriority,
+  GoalRuntimeHandoff,
+  GoalStatusReport,
   GoalStep,
   GoalTaskLink,
   GoalVerdictSource,
@@ -784,6 +784,17 @@ export type {
   GoalVerifierQuote,
 } from './goal-contract.js';
 export { GOAL_CONTRACT_SCHEMA, GOAL_HOST_CHECK_KINDS } from './goal-contract.js';
+// === CLEO Goal runtime bin wire shapes (T13819 / T13820 / T13821) ===
+export type {
+  GoalRuntimeBudgetPart,
+  GoalRuntimeCriterion,
+  GoalRuntimeError,
+  GoalRuntimeInstall,
+  GoalRuntimePluginEntry,
+  GoalRuntimeRunStatus,
+  GoalRuntimeStatus,
+} from './goal-runtime.js';
+export { GOAL_RUNTIME_SCHEMA_VERSION } from './goal-runtime.js';
 // === Graph Intelligence Types (T512, T529, T1862, T9145) ===
 export type {
   AmbiguousProvenance,

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

@@ -490,7 +490,6 @@ export const SYNC_WRITE_INVARIANTS: readonly SyncWriteInvariant[] = Object.freez
       ['status'],
       ['PB-1', 'PB-4', 'PB-7', 'P33'],
       'an approval goes pending→decided once',
-      ['tasks_playbook_approvals', 'playbook_approvals'],
     ),
   ),
   implemented(
@@ -548,15 +547,16 @@ export const SYNC_WRITE_INVARIANTS: readonly SyncWriteInvariant[] = Object.freez
       'the projection keeps the max-HLC head; a losing concurrent head is recorded (conflict_count/last_conflict_json), never silently shadowed',
   },
   // T13355 — the docs write path adopts a legacy doc into the conduit family
-  // once (identity shell keyed by the immutable uid); the read-back guard is
-  // a local write-confirmation, not a merge rule.
+  // once (identity shell keyed by the immutable uid). T13586: the rule is
+  // about id minting across replicas, so it is identity-layer — the shell's
+  // uid and birth_fp derive from the legacy doc, not the adopting device.
   {
     id: 'docs.doc.adopt-once',
-    class: 'not-sync-relevant',
+    class: 'identity-layer',
     tables: ['conduit_attachments'],
     sites: [],
     reason:
-      'adopting a legacy doc inserts one immutable-uid identity shell; losing the write is refused loudly at the writer, not merged',
+      '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',
   },
   // 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.

package/src/operations/docs.ts

@@ -1114,7 +1114,8 @@ export interface DocsDoctorDiagnostic {
     | 'wikilinks-drift'
     | 'legacy-store-present'
     | 'legacy-blob-coverage'
-    | 'stale-drafts';
+    | 'stale-drafts'
+    | 'conduit-history-gaps';
   /** `error` should be fixed promptly; `info` is observational. */
   severity: 'info' | 'warn' | 'error';
   /** Total offenders found (may exceed `items.length`). */
@@ -1157,7 +1158,7 @@ export interface DocsDoctorResult {
   olderThanDays: number;
   /** Backup receipt that authorised this run (null on dry runs). */
   backupReceiptPath: string | null;
-  /** All seven diagnostics, in declaration order. */
+  /** All eight diagnostics, in declaration order. */
   diagnostics: readonly DocsDoctorDiagnostic[];
   /** Repair plan (dry run) or executed repairs (apply). */
   repairs: readonly DocsDoctorRepairAction[];