@cleocode/contracts 2026.10.27 → 2026.11.1-canary.2

package/src/docs/modernize.ts

@@ -0,0 +1,376 @@
+/**
+ * Docs modernize contract — the plan and receipt of `cleo docs modernize`.
+ *
+ * `cleo docs modernize <path>` turns a messy docs folder into clean, linked
+ * CleoDocs. A dry run produces a {@link DocsModernizePlan}: one
+ * {@link DocsModernizePlanRow} per markdown or text file, carrying the kind,
+ * the stable slug, the disposition and the reasons (including every System
+ * One judgment that was asked). `--apply` executes a plan and writes a
+ * {@link DocsModernizeReceipt}; every receipt op records the state it
+ * replaced, so `--rollback <runId>` can reverse the run.
+ *
+ * Types only — the planner and applier live in
+ * `packages/core/src/docs/modernize/`.
+ *
+ * @task T14113
+ * @epic T14106
+ */
+
+import { z } from 'zod';
+
+/** What modernize does with one file. */
+export const DOCS_MODERNIZE_DISPOSITIONS = ['keep', 'rename', 'merge-into', 'delete'] as const;
+
+/**
+ * One of {@link DOCS_MODERNIZE_DISPOSITIONS}.
+ *
+ * - `keep` — the file already sits at its canonical path; it is ingested as is.
+ * - `rename` — the file moves to `<kind folder>/<slug>.md` and is ingested there.
+ * - `merge-into` — the file duplicates another; its content folds into the
+ *   survivor named by `target`, and the file is superseded and removed.
+ * - `delete` — the file carries nothing worth keeping (empty, or byte-identical
+ *   to the survivor); it is superseded by `target` when one exists and removed.
+ */
+export type DocsModernizeDisposition = (typeof DOCS_MODERNIZE_DISPOSITIONS)[number];
+
+/** Where an acted-on answer came from. */
+export type DocsModernizeJudgmentSource = 'provider' | 'cache' | 'fallback';
+
+/** The two System One questions modernize asks. */
+export type DocsModernizeJudgmentQuestion = 'classify' | 'merge';
+
+/**
+ * One judgment taken for a plan row: the rule answer, the System One answer
+ * when one was asked, and which of the two acted.
+ */
+export interface DocsModernizeJudgment {
+  /** Which question was judged. */
+  readonly question: DocsModernizeJudgmentQuestion;
+  /** Decision-site id the question was asked through (`docs.modernize.*`). */
+  readonly site: string;
+  /** Effective site mode (`off`, `shadow` or `on`). */
+  readonly mode: 'off' | 'shadow' | 'on';
+  /** The rule fallback's answer. */
+  readonly ruleAnswer: string;
+  /** The System One answer, or null when none came back (off, unreachable, invalid). */
+  readonly decidedAnswer: string | null;
+  /** Confidence of the System One answer, or null when none came back. */
+  readonly decidedConfidence: number | null;
+  /** Where the decided answer came from; `fallback` when the rule answered. */
+  readonly source: DocsModernizeJudgmentSource;
+  /** The answer the plan acts on. */
+  readonly acted: string;
+}
+
+/** One file's proposal. */
+export interface DocsModernizePlanRow {
+  /** Path relative to the modernize root, POSIX separators. */
+  readonly path: string;
+  /** SHA-256 of the file bytes, hex. */
+  readonly sha256: string;
+  /** Taxonomy kind (a `DocKindRegistry` kind). */
+  readonly kind: string;
+  /** Stable slug: no task, session or date tokens. */
+  readonly slug: string;
+  /** Human title (first H1, else derived from the slug). */
+  readonly title: string;
+  /** What happens to the file. */
+  readonly disposition: DocsModernizeDisposition;
+  /**
+   * For `keep` / `rename`: the canonical path relative to the root.
+   * For `merge-into` / `delete`: the survivor's slug, or null when there is none.
+   */
+  readonly target: string | null;
+  /** Why, one line each. */
+  readonly reasons: readonly string[];
+  /** Every System One question asked for this row. */
+  readonly judgments: readonly DocsModernizeJudgment[];
+  /** Task (`T####`) and decision (`D####`) ids the old path named; kept as links, not in the slug. */
+  readonly ownerTasks: readonly string[];
+  /** The kind's folder the file belongs in (`''` for the root). */
+  readonly category: string;
+  /** Tracked files outside the root that cite the old path (listed, never rewritten). */
+  readonly refs: readonly string[];
+  /** True when the row came from an override file rather than the rules. */
+  readonly overridden: boolean;
+  /** Code paths this doc documents (from the override; written to front matter by the caller). */
+  readonly covers: readonly string[];
+  /** True when the old name broke the slug rule (task, session or date tokens) and the new one does not. */
+  readonly baselineRemove: boolean;
+}
+
+/** One reviewer decision for a path; it wins over the rules and System One. */
+export interface DocsModernizeOverride {
+  /** What happens to the file. */
+  readonly disposition: DocsModernizeDisposition;
+  /** Canonical path (`keep`/`rename`) or survivor slug (`merge-into`/`delete`). */
+  readonly target?: string;
+  /** Why; recorded on the plan row. */
+  readonly reason: string;
+  /** Kind to use instead of the classified one. */
+  readonly kind?: string;
+  /** Slug to use instead of the derived one. */
+  readonly slug?: string;
+  /** Code paths this doc documents, copied onto the plan row. */
+  readonly covers?: readonly string[];
+}
+
+/** `--overrides <file>`: decisions keyed by path relative to the modernize root. */
+export type DocsModernizeOverrides = Readonly<Record<string, DocsModernizeOverride>>;
+
+/** A dry-run proposal for a whole tree. */
+export interface DocsModernizePlan {
+  /** Absolute modernize root. */
+  readonly root: string;
+  /** ISO 8601 time the plan was made. */
+  readonly generatedAt: string;
+  /** One row per scanned file, sorted by path. */
+  readonly rows: readonly DocsModernizePlanRow[];
+  /** Files counted per disposition. */
+  readonly counts: Readonly<Record<DocsModernizeDisposition, number>>;
+  /**
+   * `tree` reorganises the folder; `store-only` ingests every file into the
+   * store (task-owned, slugless) and leaves the folder untouched; `store`
+   * re-kinds and re-slugs the rows already in the store (`storeRows`, T14118).
+   */
+  readonly mode: 'tree' | 'store-only' | 'store';
+  /** Store-mode rows (`mode: 'store'`); absent or empty otherwise. */
+  readonly storeRows?: readonly DocsModernizeStoreRow[];
+}
+
+/**
+ * One existing store doc in a `--store` plan (T14118): its kind and slug now,
+ * and what modernize proposes. An unchanged field repeats the current value.
+ */
+export interface DocsModernizeStoreRow {
+  /** Attachment row id. */
+  readonly attachmentId: string;
+  /** Content hash. */
+  readonly sha256: string;
+  /** Current slug (null for a slugless row). */
+  readonly slug: string | null;
+  /** Proposed slug; the current one stays resolvable as an alias. */
+  readonly newSlug: string | null;
+  /** Current kind (null when untyped). */
+  readonly kind: string | null;
+  /** Proposed kind. */
+  readonly newKind: string;
+  /** Task ids the old slug named; linked to the doc as task refs. */
+  readonly ownerTasks: readonly string[];
+  /** Why, one line each. */
+  readonly reasons: readonly string[];
+  /** Every System One question asked for this row. */
+  readonly judgments: readonly DocsModernizeJudgment[];
+}
+
+/** The reversible steps an apply run takes. */
+export const DOCS_MODERNIZE_OPS = [
+  'ingest',
+  'merge',
+  'fold',
+  'supersede',
+  'write-file',
+  'remove-file',
+  'link',
+  'rekind',
+  'reslug',
+  'link-task',
+] as const;
+
+/** One of {@link DOCS_MODERNIZE_OPS}. */
+export type DocsModernizeOpKind = (typeof DOCS_MODERNIZE_OPS)[number];
+
+/**
+ * Write-ahead state of a receipt op: written `pending` before the step acts,
+ * `done` after it, `reversed` once a rollback has undone it.
+ */
+export type DocsModernizeOpState = 'pending' | 'done' | 'reversed';
+
+/** Store values a step replaced, so a rollback restores them exactly. */
+export interface DocsModernizeOpPrior {
+  /** `supersede`: the older row's lifecycle status before the step. */
+  readonly lifecycleStatus?: string | null;
+  /** `supersede`: the older row's `superseded_by` before the step. */
+  readonly supersededBy?: string | null;
+  /** `supersede`: the newer row's `supersedes` before the step. */
+  readonly supersedes?: string | null;
+  /** `merge`: the row that held the slug before the update. */
+  readonly previousAttachmentId?: string | null;
+  /** `merge`: the row the update moved the slug to. */
+  readonly newAttachmentId?: string | null;
+  /** `link`: the slug's `links-to` targets before the step. */
+  readonly linkTargets?: readonly string[];
+  /** `rekind`: the row's kind before the step. */
+  readonly kind?: string | null;
+}
+
+/**
+ * One step with the state it replaced.
+ *
+ * - `ingest` — a doc stored under `slug` (or slugless) for `ownerId`; `attachmentId` is the row.
+ * - `merge` — the stored doc `slug` was updated with merged content; `prior` names both rows.
+ * - `fold` — the file `path` was folded into the survivor `target` (content went there).
+ * - `supersede` — `slug` was superseded by `target`; `prior` holds the replaced pointers.
+ * - `write-file` — `path` was written; `beforeSha256` is the old bytes, or null when it was new.
+ * - `remove-file` — `path` was removed; `beforeSha256` names the bytes kept for rollback.
+ * - `link` — the `links-to` edges leaving `slug` were set; `prior.linkTargets` holds the old set.
+ * - `rekind` — the row `attachmentId` changed kind; `prior.kind` holds the old one (T14118).
+ * - `reslug` — `slug` was renamed to `target`; `slug` stays an alias (T14118).
+ * - `link-task` — the row `attachmentId` gained a ref to task `ownerId` (T14118).
+ */
+export interface DocsModernizeReceiptOp {
+  /** Step kind. */
+  readonly op: DocsModernizeOpKind;
+  /** Write-ahead state. */
+  readonly state: DocsModernizeOpState;
+  /** Doc slug the step touched, when any. */
+  readonly slug: string | null;
+  /** File path relative to the root, when any. */
+  readonly path: string | null;
+  /** The other end: survivor slug for `supersede` and `fold`. */
+  readonly target: string | null;
+  /** Attachment row created or touched by the step, when any. */
+  readonly attachmentId: string | null;
+  /** Owner the `ingest` ref was made for (`T####` or the project sentinel); rollback drops that ref. */
+  readonly ownerId: string | null;
+  /** Content the step replaced or removed, when any. */
+  readonly beforeSha256: string | null;
+  /** Content the step wrote, when any. */
+  readonly afterSha256: string | null;
+  /** Store values the step replaced. */
+  readonly prior?: DocsModernizeOpPrior;
+}
+
+/** The record of one apply run; the input to rollback. */
+export interface DocsModernizeReceipt {
+  /** Run id (`dm-<timestamp>`); names the receipt file. */
+  readonly runId: string;
+  /** Absolute modernize root. */
+  readonly root: string;
+  /** ISO 8601 time the run started. */
+  readonly appliedAt: string;
+  /** SHA-256 of the canonical JSON of the plan that was applied. */
+  readonly planSha256: string;
+  /** Steps in the order they ran. */
+  readonly ops: readonly DocsModernizeReceiptOp[];
+  /** Wikilink edges in the graph after the run. */
+  readonly edgeCount: number;
+  /** Every scanned file whose bytes were hash-verified in the blob store, before any removal. */
+  readonly blobs: readonly { readonly path: string; readonly sha256: string }[];
+  /** Files moved, relative to the root (stage exactly these). */
+  readonly moves: readonly { readonly from: string; readonly to: string }[];
+  /** Files removed, relative to the root. */
+  readonly deleted: readonly string[];
+  /** ISO 8601 time the run was rolled back, or null. */
+  readonly rolledBackAt: string | null;
+  /** Wall time of the apply, in ms (store mode). */
+  readonly durationMs?: number;
+}
+
+// ─── Schemas (a plan or receipt read from disk is untrusted input) ───────────
+
+const judgmentSchema = z.object({
+  question: z.enum(['classify', 'merge']),
+  site: z.string(),
+  mode: z.enum(['off', 'shadow', 'on']),
+  ruleAnswer: z.string(),
+  decidedAnswer: z.string().nullable(),
+  decidedConfidence: z.number().nullable(),
+  source: z.enum(['provider', 'cache', 'fallback']),
+  acted: z.string(),
+});
+
+const relPath = z.string().min(1).max(1024);
+
+/** Shape check for a {@link DocsModernizePlan} read from a `--plan` file. */
+export const docsModernizePlanSchema = z.object({
+  root: z.string().min(1),
+  generatedAt: z.string(),
+  mode: z.enum(['tree', 'store-only']),
+  counts: z.record(z.enum(DOCS_MODERNIZE_DISPOSITIONS), z.number()),
+  rows: z.array(
+    z.object({
+      path: relPath,
+      sha256: z.string().regex(/^[0-9a-f]{64}$/),
+      kind: z.string().min(1),
+      slug: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+      title: z.string(),
+      disposition: z.enum(DOCS_MODERNIZE_DISPOSITIONS),
+      target: z.string().min(1).max(1024).nullable(),
+      reasons: z.array(z.string()),
+      judgments: z.array(judgmentSchema),
+      ownerTasks: z.array(z.string().regex(/^[TD]\d+$/)),
+      category: z.string(),
+      refs: z.array(z.string()),
+      overridden: z.boolean(),
+      covers: z.array(z.string()),
+      baselineRemove: z.boolean(),
+    }),
+  ),
+});
+
+/** Shape check for an `--overrides` file ({@link DocsModernizeOverrides}). */
+export const docsModernizeOverridesSchema = z.record(
+  relPath,
+  z.object({
+    disposition: z.enum(DOCS_MODERNIZE_DISPOSITIONS),
+    target: z.string().min(1).max(1024).optional(),
+    reason: z.string().min(1),
+    kind: z.string().min(1).optional(),
+    slug: z
+      .string()
+      .regex(/^[a-z0-9][a-z0-9-]*$/)
+      .optional(),
+    covers: z.array(z.string()).optional(),
+  }),
+);
+
+/** Shape check for one receipt op. */
+const receiptOpSchema = z.object({
+  op: z.enum(DOCS_MODERNIZE_OPS),
+  state: z.enum(['pending', 'done', 'reversed']),
+  slug: z.string().nullable(),
+  path: relPath.nullable(),
+  target: z.string().nullable(),
+  attachmentId: z.string().nullable(),
+  ownerId: z.string().nullable(),
+  beforeSha256: z
+    .string()
+    .regex(/^[0-9a-f]{64}$/)
+    .nullable(),
+  afterSha256: z
+    .string()
+    .regex(/^[0-9a-f]{64}$/)
+    .nullable(),
+  prior: z
+    .object({
+      lifecycleStatus: z.string().nullable().optional(),
+      supersededBy: z.string().nullable().optional(),
+      supersedes: z.string().nullable().optional(),
+      previousAttachmentId: z.string().nullable().optional(),
+      newAttachmentId: z.string().nullable().optional(),
+      linkTargets: z.array(z.string()).optional(),
+      kind: z.string().nullable().optional(),
+    })
+    .optional(),
+});
+
+/** Shape check for one line of a run's write-ahead journal (`<runId>.ops.jsonl`). */
+export const docsModernizeJournalLineSchema = receiptOpSchema.extend({
+  i: z.number().int().min(0),
+});
+
+/** Shape check for a {@link DocsModernizeReceipt} read back for rollback. */
+export const docsModernizeReceiptSchema = z.object({
+  runId: z.string().regex(/^dm-[\w-]+$/),
+  root: z.string().min(1),
+  appliedAt: z.string(),
+  planSha256: z.string(),
+  edgeCount: z.number(),
+  rolledBackAt: z.string().nullable(),
+  blobs: z.array(z.object({ path: relPath, sha256: z.string() })),
+  moves: z.array(z.object({ from: relPath, to: relPath })),
+  deleted: z.array(relPath),
+  ops: z.array(receiptOpSchema),
+  durationMs: z.number().optional(),
+});

package/src/docs-taxonomy.ts

@@ -112,10 +112,16 @@ export interface DocKindMetadata {
    * @epic T10157
    */
   readonly requiredSections?: ReadonlyArray<string>;
+  /**
+   * When `true`, docs of this kind live only in the CLEO doc store and are
+   * never published to a repository mirror (T14107, D11210: session
+   * handoffs are exactly the rot published docs must not carry).
+   */
+  readonly storeOnly?: boolean;
 }
 
 // ---------------------------------------------------------------------------
-// Built-in registry (10 canonical kinds)
+// Built-in registry (14 canonical kinds)
 // ---------------------------------------------------------------------------
 
 /**
@@ -167,6 +173,7 @@ export const BUILTIN_DOC_KINDS: ReadonlyArray<DocKindMetadata> = [
     publishDir: 'docs/handoff',
     requiresEntityId: false,
     requiredSections: ['Context', 'State', 'Next-Steps'],
+    storeOnly: true,
   },
   {
     kind: 'note',
@@ -225,6 +232,42 @@ export const BUILTIN_DOC_KINDS: ReadonlyArray<DocKindMetadata> = [
     entityIdPattern: /^t\d+(-.+)?$/,
     requiredSections: ['Root-Cause', 'Action', 'Schedule', 'Detection'],
   },
+  {
+    kind: 'guide',
+    label: 'Guide',
+    description: 'How-to guide: the steps to get a task done (T14107)',
+    defaultOwnerKind: 'project',
+    publishDir: 'docs/guide',
+    requiresEntityId: false,
+    requiredSections: [],
+  },
+  {
+    kind: 'concept',
+    label: 'Concept',
+    description: 'Explanation of how and why the product works (T14107)',
+    defaultOwnerKind: 'project',
+    publishDir: 'docs/concept',
+    requiresEntityId: false,
+    requiredSections: [],
+  },
+  {
+    kind: 'reference',
+    label: 'Reference',
+    description: 'Reference: APIs, CLI, registries and formats (T14107)',
+    defaultOwnerKind: 'project',
+    publishDir: 'docs/reference',
+    requiresEntityId: false,
+    requiredSections: [],
+  },
+  {
+    kind: 'migration',
+    label: 'Migration',
+    description: 'Upgrade or data-migration guide (T14107)',
+    defaultOwnerKind: 'project',
+    publishDir: 'docs/migration',
+    requiresEntityId: false,
+    requiredSections: [],
+  },
 ];
 
 /**

package/src/done-plan.ts

@@ -258,8 +258,21 @@ export interface DonePlanTypedGate {
   kind: string;
   /** Requirement id, when the gate declares one. */
   req?: string;
-  /** Latest stored result; `not-run` when none is stored, or when a stored pass would not stand. */
-  status: 'pass' | 'fail' | 'not-run';
+  /**
+   * Latest stored result; `not-run` when none is stored, or when a stored pass
+   * would not stand. `cached` (T14138): nothing is stored, but the evidence
+   * cache holds a pass for this tree and environment (from `cleo verify
+   * --run`), which the next evidence write binds without running the gate.
+   */
+  status: 'pass' | 'fail' | 'not-run' | 'cached';
+  /** When the cached pass was recorded (`cached` only). */
+  cachedAt?: string;
+  /**
+   * Why a `not-run` gate's cache entry did not match: the key part that moved
+   * since the last cached pass (HEAD, dirty fingerprint, tree, inputs or
+   * environment), when a recent entry explains it (T14138).
+   */
+  cacheMiss?: string;
   /**
    * Why a stored pass is `not-run`: the refusal `cleo complete` would raise
    * from this tree and environment (T14063).
@@ -334,6 +347,12 @@ export interface DonePlan {
   commands: string[];
   /** True when no blocker remains and `commands` would succeed as planned. */
   ready: boolean;
+  /**
+   * Why the plan is not ready when no blocker says so (T14095): the task is
+   * already done, or there is no command to run. A plan with `ready: false`
+   * always carries a blocker or this reason.
+   */
+  readyReason?: string;
   /** The single next step: the first blocker's, or the first command. */
   next: DoneNextStep | null;
   /**
@@ -341,6 +360,12 @@ export interface DonePlan {
    * by the same function `cleo complete` runs, from local refs only.
    */
   integration?: WorktreeIntegrationPlan;
+  /**
+   * Untracked files the change's evidence leaves out (T14125): scope is the
+   * task's commits against the base plus uncommitted tracked edits (staged
+   * and `git add -N` files included), never a stray file in the checkout.
+   */
+  untrackedSetAside?: string[];
 }
 
 /** One tool `cleo done` ran (or reused from the ADR-061 cache) before recording. */

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,
@@ -605,6 +658,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',
@@ -835,6 +890,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 +1003,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) {