@cleocode/contracts 2026.9.21 → 2026.9.23

package/src/__tests__/evidence-atom-schema.test.ts

@@ -499,6 +499,28 @@ describe('parseEvidenceString (T10337)', () => {
 
 // ─── GATE_EVIDENCE_REQUIREMENTS — gate-to-atom mapping ─────────────────────
 
+describe('pr:/ci: component references (T12671)', () => {
+  it('pr:<component>@<integration> names the integration PR and its component', () => {
+    expect(parseEvidenceString('pr:42@41')).toEqual([
+      { kind: 'pr', prNumber: 41, componentPrNumber: 42 },
+    ]);
+    expect(parseEvidenceString('ci:42@41')).toEqual([
+      { kind: 'ci', prNumber: 41, componentPrNumber: 42 },
+    ]);
+    expect(parseEvidenceString('pr:41')).toEqual([{ kind: 'pr', prNumber: 41 }]);
+  });
+
+  it.each(['pr:42@42', 'pr:42@', 'pr:@41', 'ci:0@41', 'pr:42@4x'])('rejects %s', (raw) => {
+    expect(() => parseEvidenceString(raw)).toThrow(EvidenceParseError);
+  });
+
+  it('the schema accepts the component field', () => {
+    expect(
+      EvidenceAtomSchema.safeParse({ kind: 'ci', prNumber: 41, componentPrNumber: 42 }).success,
+    ).toBe(true);
+  });
+});
+
 describe('GATE_EVIDENCE_REQUIREMENTS (T10337)', () => {
   it('covers every VerificationGate', () => {
     const expected: VerificationGate[] = [
@@ -662,7 +684,8 @@ describe('formatGateRequirement (T10337)', () => {
     expect(s).toContain('[decision AND note]');
     expect(s).toContain('[pr AND files]');
     // Joiner between combinations is ' OR '.
-    expect(s.split(' OR ').length).toBe(5);
+    // T12689: + [pr AND note] for a deletion-only PR.
+    expect(s.split(' OR ').length).toBe(6);
   });
 
   it('formats single-element combination without AND', () => {
@@ -737,7 +760,7 @@ describe('validateEvidenceForGate failure surface (T9949)', () => {
     if (!r.ok) {
       // Error includes the same artifact requirement as the validator.
       expect(r.message).toBe(
-        "Gate 'implemented' requires evidence: [commit AND files] OR [commit AND note] OR [decision AND files] OR [decision AND note] OR [pr AND files]",
+        "Gate 'implemented' requires evidence: [commit AND files] OR [commit AND note] OR [decision AND files] OR [decision AND note] OR [pr AND files] OR [pr AND note]",
       );
       // New rich hint includes the same content as formatGateRequirementHint.
       expect(r.hint).toBe(formatGateRequirementHint('implemented'));

package/src/acceptance-gate-schema.ts

@@ -536,7 +536,10 @@ export const acceptanceGateResultSchema = z
           message: 'Result cannot precede input capture',
         });
       const executable = ['test', 'command', 'lint'].includes(result.kind);
-      if (executable && !binding.invocation)
+      // T12718: a command the runner refused to split (shell syntax, open
+      // quote) never had an invocation. It is bound as an unmet `error` so the
+      // rest of its batch still records; any verdict needs the invocation.
+      if (executable && !binding.invocation && result.result !== 'error')
         context.addIssue({
           code: 'custom',
           path: ['binding', 'invocation'],

package/src/data-accessor.ts

@@ -255,6 +255,8 @@ export interface AcBindingRow {
 
 /** Query options for bounded reads from the append-only task audit log. @task T10594 */
 export interface TaskAuditLogQuery {
+  /** Exact audit row ids (T12693: revert one ranking change). */
+  ids?: readonly string[];
   taskIds?: readonly string[];
   actions?: readonly string[];
   since?: string;
@@ -271,6 +273,8 @@ export interface TaskAuditLogRow {
   detailsJson: string | null;
   beforeJson: string | null;
   afterJson: string | null;
+  /** Session the mutation ran in, when recorded (T12693). */
+  sessionId?: string | null;
 }
 
 /**

package/src/decide-sites.ts

@@ -0,0 +1,179 @@
+/**
+ * Decision-site registry contracts — the "decision ladder as code" (spec
+ * `system-one-integration` §3, owner decisions D11158 and D11159).
+ *
+ * Every place CLEO makes a judgement is a decision site: it has one primary
+ * rung, an ordered ladder of rungs it may escalate to, a fallback, an
+ * owner-escalation rule, a mode and (to act on a System One answer) go-live
+ * evidence. The registry rows live in `packages/core/src/decide/sites/`;
+ * these are their types.
+ *
+ * Types and const data only (arch gate 10).
+ *
+ * @task T12662
+ * @epic T12486
+ */
+
+/**
+ * The decision rungs, cheapest first. Escalation only moves up this list.
+ *
+ * - `rule` — the answer follows from data (ids, statuses, thresholds).
+ * - `system-one` — a typed judgement over text with a small fixed answer set.
+ * - `generative` — the output must be free text or code.
+ * - `agent` — multi-step work.
+ * - `owner` — authority only the owner can take (the ask tool).
+ */
+export const DECISION_RUNGS = ['rule', 'system-one', 'generative', 'agent', 'owner'] as const;
+
+/** One rung of the decision ladder. */
+export type DecisionRung = (typeof DECISION_RUNGS)[number];
+
+/** Site modes: `off` never asks, `shadow` asks and audits, `on` acts. */
+export const DECISION_SITE_MODES = ['off', 'shadow', 'on'] as const;
+
+/** How a site uses its System One rung. */
+export type DecisionSiteModeValue = (typeof DECISION_SITE_MODES)[number];
+
+/** The shape of the question a site answers. */
+export type DecisionSiteQuestionType =
+  | 'noul'
+  | 'choice'
+  | 'score'
+  | 'text'
+  | 'multi-step'
+  | 'owner-choice';
+
+/**
+ * When a site may put a question to the owner.
+ *
+ * - `never` — the site never asks the owner.
+ * - `escalate-only` — it may add an owner question, never clear one.
+ * - `below-floor` — it asks the owner when every lower rung is below its floor.
+ * - `always` — the owner always decides.
+ */
+export type DecisionSiteOwnerEscalation = 'never' | 'escalate-only' | 'below-floor' | 'always';
+
+/** Classes of text a site may send off the machine (spec §8). */
+export type DecisionSiteTextClass =
+  | 'task-text'
+  | 'memory-text'
+  | 'diff'
+  | 'skill-text'
+  | 'external-text';
+
+/** Measured evidence that lets a site act on its System One answer (`mode: on`). */
+export interface DecisionSiteGoLive {
+  /** Canonical doc slug holding the measurement. */
+  readonly evidenceDoc: string;
+  /** ISO date of the measurement. */
+  readonly measuredAt: string;
+  /** Number of labelled decisions measured. */
+  readonly n: number;
+  /** Metric name, e.g. `precision@acting-class`. */
+  readonly metric: string;
+  /** Measured value. */
+  readonly value: number;
+  /** Floor the value had to clear. */
+  readonly floor: number;
+}
+
+/** One registry row: everything CLEO knows about a decision site. */
+export interface DecisionSiteDefinition {
+  /** Site id; the string `decide()` and the audit log use, e.g. `tasks.duplicate-detection`. */
+  readonly id: string;
+  /** Human title. */
+  readonly title: string;
+  /** Repo-relative files where the site lives. */
+  readonly files: readonly string[];
+  /** The shape of the question. */
+  readonly questionType: DecisionSiteQuestionType;
+  /** The rung that answers first. */
+  readonly primaryRung: DecisionRung;
+  /** Rungs it may escalate to, in order, all above the primary. */
+  readonly ladder: readonly DecisionRung[];
+  /** What acts when the primary is unavailable. */
+  readonly fallback: DecisionRung | 'none';
+  /**
+   * Minimum confidence per question before `on` may act on a System One
+   * answer. The key `*` applies to every question of the site.
+   */
+  readonly floors?: Readonly<Record<string, number>>;
+  /** When the site may ask the owner. */
+  readonly ownerEscalation: DecisionSiteOwnerEscalation;
+  /** Config key holding the mode (the existing `decide.sites.*` keys, D11159). */
+  readonly modeKey?: string;
+  /** Config key opting the site into its generative rung (`decide.generativeFallback.*`). */
+  readonly generativeKey?: string;
+  /** Mode when the config key is unset. */
+  readonly defaultMode: DecisionSiteModeValue;
+  /** Generative rung: the role or system key it resolves its model with. */
+  readonly llmSystemKey?: string;
+  /** True for a site on a write path: 300 ms budget, never blocks the write. */
+  readonly writePath: boolean;
+  /** Text classes it sends to a provider. */
+  readonly sends: readonly DecisionSiteTextClass[];
+  /** Go-live evidence, required before a System One site runs `on`. */
+  readonly goLive?: DecisionSiteGoLive;
+  /** Owning task. */
+  readonly task: string;
+  /** Free-form note (constraints such as "interactive only"). */
+  readonly note?: string;
+}
+
+/** Audit counts for one site over the last seven days. */
+export interface DecisionSiteActivity {
+  /** Audit lines written for the site. */
+  readonly asked: number;
+  /** Answered by the provider. */
+  readonly provider: number;
+  /** Answered from the decision cache. */
+  readonly cache: number;
+  /** Answered by the fallback. */
+  readonly fallback: number;
+  /** Escalated to a higher rung (0 until the ladder executor lands, T12665). */
+  readonly escalated: number;
+  /** Share of compared shadow lines where decision and heuristic agreed, when any were compared. */
+  readonly agreement?: number;
+}
+
+/** One site as `cleo decide sites` reports it. */
+export interface DecisionSiteSummary {
+  /** Site id. */
+  readonly id: string;
+  /** Human title. */
+  readonly title: string;
+  /** Question shape. */
+  readonly questionType: DecisionSiteQuestionType;
+  /** Primary rung. */
+  readonly primaryRung: DecisionRung;
+  /** Escalation ladder. */
+  readonly ladder: readonly DecisionRung[];
+  /** Fallback. */
+  readonly fallback: DecisionRung | 'none';
+  /** Owner-escalation rule. */
+  readonly ownerEscalation: DecisionSiteOwnerEscalation;
+  /** Registry default mode. */
+  readonly mode: DecisionSiteModeValue;
+  /** Mode set in config, when the site has a mode key and it is set. */
+  readonly configuredMode?: DecisionSiteModeValue;
+  /** Mode in force: `off` for a System One site while no provider is configured. */
+  readonly effectiveMode: DecisionSiteModeValue;
+  /** Config key holding the mode, when the site has one. */
+  readonly modeKey?: string;
+  /** Go-live evidence, when recorded. */
+  readonly goLive?: DecisionSiteGoLive;
+  /** Owning task. */
+  readonly task: string;
+  /** Audit activity over the last seven days. */
+  readonly last7d: DecisionSiteActivity;
+}
+
+/** Result of `cleo decide sites`. */
+export interface DecisionSitesListResult {
+  /** Whether a System One provider is configured (else System One sites are `off`). */
+  readonly providerConfigured: boolean;
+  /** Registered sites total, before filters. */
+  readonly total: number;
+  /** Matching sites. */
+  readonly sites: readonly DecisionSiteSummary[];
+}

package/src/decide.ts

@@ -143,6 +143,17 @@ export interface DecisionRequest {
   readonly state: DecisionState;
   /** Question name → question (1–32 entries). Names key the answers in {@link DecisionOutcome}. */
   readonly questions: Readonly<Record<string, DecisionQuestion>>;
+  /**
+   * Language hint (e.g. `en`). Sent only to a provider whose capabilities
+   * include `langHint`; others never see it (T12664).
+   */
+  readonly lang?: string;
+  /**
+   * Provider-side answer cache. `false` asks a provider with `cacheControl`
+   * not to answer from its cache (real latency, sensitive text). Ignored by
+   * providers without the capability.
+   */
+  readonly cache?: boolean;
 }
 
 /** Answer to a {@link NoulDecisionQuestion}. */
@@ -196,14 +207,100 @@ export interface DecisionOutcome {
   readonly latencyMs: number;
   /** Provider-reported cost in US dollars, when known. */
   readonly costUsd?: number;
+  /** Provider-reported cost in integer micro-dollars, when known (T12664). */
+  readonly costMicros?: number;
+  /** Account balance in integer micro-dollars reported with this answer, when known. */
+  readonly balanceMicros?: number;
+  /** Provider model checkpoint that answered, when reported. */
+  readonly checkpoint?: string;
   /** Provider-reported input-token count, when known. */
   readonly inputTokens?: number;
 }
 
+// ─── Provider kinds (T12713) ─────────────────────────────────────────────────
+
+/**
+ * Every supported decision-provider kind, recommended first.
+ *
+ * - `layahost` — the hosted provider at {@link LAYAHOST_BASE_URL}; the user
+ *   supplies only an API key.
+ * - `jev`      — any other Jev-compatible endpoint; the user supplies the URL.
+ */
+export const DECISION_PROVIDER_KINDS = ['layahost', 'jev'] as const;
+
+/** A decision-provider kind. See {@link DECISION_PROVIDER_KINDS}. */
+export type DecisionProviderKind = (typeof DECISION_PROVIDER_KINDS)[number];
+
+/** Base URL of the layahost API (its OpenAPI `servers[0].url`). */
+export const LAYAHOST_BASE_URL = 'https://layahost.com';
+
+/** layahost's routing model, the default for a layahost connection. */
+export const LAYAHOST_DEFAULT_MODEL = 'laya-auto';
+
 /** Connection settings for a decision provider. */
 export interface DecisionProviderConfig {
   /** Absolute base URL of the provider's API (no trailing path to the endpoint). */
   readonly baseUrl: string;
+  /** Provider kind; absent means a custom Jev-compatible endpoint (`jev`). */
+  readonly provider?: DecisionProviderKind;
+}
+
+// ─── Provider capabilities (T12664) ──────────────────────────────────────────
+
+/**
+ * What a decision provider can do beyond the Jev minimum
+ * (`POST /v1/systemone`, 32 questions, 32,000-character state). A caller asks
+ * for a capability; the client degrades when it is absent (spec
+ * `system-one-integration` §2.2).
+ */
+export interface DecisionProviderCapabilities {
+  /** Wire protocol the provider speaks. */
+  readonly wire: string;
+  /** Most questions one request may carry. */
+  readonly maxQuestionsPerRequest: number;
+  /** Largest state, in characters. */
+  readonly maxStateChars: number;
+  /** Batch endpoint limits, when the provider has one. */
+  readonly batch?: { readonly maxRequests: number; readonly maxQuestions: number };
+  /** Built-in template names, when the provider has templates. */
+  readonly templates?: readonly string[];
+  /** Server-side flows are available. */
+  readonly flows?: boolean;
+  /** A usage/balance endpoint and cost headers are available. */
+  readonly usage?: boolean;
+  /** The request's `cache` field is honoured. */
+  readonly cacheControl?: boolean;
+  /** The request's `lang` field is honoured. */
+  readonly langHint?: boolean;
+  /** How the provider reports cost. */
+  readonly reportsCost?: 'micros' | 'usd' | false;
+}
+
+/** The Jev minimum every provider supports; the default when a provider reports nothing. */
+export const JEV_MINIMUM_CAPABILITIES: DecisionProviderCapabilities = {
+  wire: 'jev-systemone/1',
+  maxQuestionsPerRequest: 32,
+  maxStateChars: 32_000,
+  reportsCost: 'usd',
+};
+
+/** One item of a batch call: its outcome, or why it failed. */
+export type DecisionBatchItem =
+  | { readonly ok: true; readonly outcome: DecisionOutcome }
+  | { readonly ok: false; readonly status?: number; readonly errorKind: string };
+
+/** Account usage and balance as a provider reports it. */
+export interface DecisionProviderUsage {
+  /** Balance in integer micro-dollars. */
+  readonly balanceMicros?: number;
+  /** Decisions the balance still covers. */
+  readonly decisionsLeft?: number;
+  /** Plan name. */
+  readonly plan?: string;
+  /** End of the current plan period, ISO-8601. */
+  readonly periodEnd?: string;
+  /** Decisions and cost over the queried window. */
+  readonly totals?: { readonly decisions?: number; readonly costMicros?: number };
 }
 
 // ─── Zod schemas ──────────────────────────────────────────────────────────────
@@ -290,6 +387,11 @@ export const decisionQuestionSchema = z.discriminatedUnion('type', [
  */
 export const decisionRequestSchema = z.object({
   model: z.string().min(1).optional(),
+  lang: z
+    .string()
+    .regex(/^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$/)
+    .optional(),
+  cache: z.boolean().optional(),
   state: decisionStateSchema,
   questions: z.record(z.string().min(1), decisionQuestionSchema).refine(
     (questions) => {
@@ -346,10 +448,17 @@ export const decisionOutcomeSchema = z.object({
   requestId: z.string().min(1).optional(),
   latencyMs: z.number().nonnegative(),
   costUsd: z.number().nonnegative().optional(),
+  costMicros: z.number().int().nonnegative().optional(),
+  balanceMicros: z.number().int().optional(),
+  checkpoint: z.string().min(1).optional(),
   inputTokens: z.number().int().nonnegative().optional(),
 });
 
+/** Zod schema for {@link DecisionProviderKind}. */
+export const decisionProviderKindSchema = z.enum(DECISION_PROVIDER_KINDS);
+
 /** Zod schema for {@link DecisionProviderConfig}; `baseUrl` must be an absolute URL. */
 export const decisionProviderConfigSchema = z.object({
   baseUrl: z.url(),
+  provider: decisionProviderKindSchema.optional(),
 });

package/src/dispatch/operations-registry.ts

@@ -814,12 +814,22 @@ export const OPERATIONS: OperationDef[] = [
     gateway: 'query' as const,
     domain: 'tasks' as const,
     operation: 'history',
-    description: 'Show task work history (time tracked per task)',
+    description:
+      'Show task work history; with taskId, the task audit trail; with ranking, who changed its priority/severity/kind/depends and why (T12693)',
     tier: 1,
     idempotent: true,
     sessionRequired: false,
     requiredParams: [],
-    params: [],
+    params: [
+      { name: 'taskId', type: 'string', required: false, description: 'Task to show history for' },
+      { name: 'limit', type: 'number', required: false, description: 'Maximum entries' },
+      {
+        name: 'ranking',
+        type: 'boolean',
+        required: false,
+        description: 'Only ranking-input changes (actor, session, reason, before/after)',
+      },
+    ] satisfies ParamDef[],
   },
   {
     gateway: 'query',
@@ -3364,6 +3374,33 @@ export const OPERATIONS: OperationDef[] = [
     ] satisfies ParamDef[],
     outputSchema: OUTPUT_CONTRACTS['tasks.assignee'],
   },
+  {
+    gateway: 'mutate',
+    domain: 'tasks',
+    operation: 'ranking.revert',
+    description:
+      'tasks.ranking.revert (mutate) — undo one recorded ranking change (priority/severity/kind/depends) as a new audited change (T12693, D11161)',
+    tier: 1,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['entryId'],
+    params: [
+      {
+        name: 'entryId',
+        type: 'string',
+        required: true,
+        description: 'ranking_changed audit row id (cleo history ranking <taskId>)',
+        cli: { positional: true },
+      },
+      { name: 'reason', type: 'string', required: false, description: 'Why it is reverted' },
+      {
+        name: 'force',
+        type: 'boolean',
+        required: false,
+        description: 'Revert even though a field changed again since',
+      },
+    ] satisfies ParamDef[],
+  },
   {
     gateway: 'mutate',
     domain: 'tasks',
@@ -8456,6 +8493,7 @@ export const OPERATIONS: OperationDef[] = [
         enum: DOCS_LIFECYCLE_STATUSES,
         description:
           'Override the new lifecycle status. Defaults to "draft" on every update. ' +
+          'Alone (no file or content) it changes only the lifecycle status. ' +
           `Valid: ${DOCS_LIFECYCLE_STATUSES.join('|')}.`,
       },
       {

package/src/done-plan.ts

@@ -119,6 +119,11 @@ export interface TaskChangeSet {
   executionRoot: string;
   /** Why {@link executionRoot} was chosen. */
   rootSource: ChangeSetRootSource;
+  /**
+   * Component PR whose change the (integration) `prNumber` landed on the
+   * default branch (T12671). Evidence is then `pr:<component>@<prNumber>`.
+   */
+  componentPrNumber?: number;
   /** Merged PR number (`source === 'pr'`). */
   prNumber?: number;
   /**
@@ -168,8 +173,23 @@ export interface TaskChangeSet {
   blockers: DonePlanBlocker[];
   /** Non-blocking observations, e.g. PR discovery that could not reach `gh`. */
   warnings: string[];
+  /**
+   * The merged-PR lookup failed (e.g. `gh` unavailable), so a non-PR change set
+   * does not prove the change is unmerged (T12656).
+   */
+  prDiscoveryFailed?: boolean;
+  /**
+   * Whether the task's PR has merged to the default branch, as the PR lookup
+   * found it — independent of `source` (T12656 review): a merged PR whose
+   * `pr:` check was refused still falls back to the task branch, and the
+   * branch outlives a squash merge. Absent when no PR was examined.
+   */
+  mergeState?: ChangeSetMergeState;
 }
 
+/** Whether a task's change has merged to the default branch. */
+export type ChangeSetMergeState = 'merged' | 'unmerged' | 'unknown';
+
 /** Planned state of one verification gate. */
 export interface DonePlanGate {
   /** Gate name. */

package/src/evidence-atom-schema.ts

@@ -198,7 +198,11 @@ export const decisionAtomSchema = z.object({
  * checks task relationship and changed artifacts. Implementation also needs
  * inspected file evidence; testing and review require actual result atoms.
  *
- * Format: `pr:<positive integer>` (e.g. `pr:357`).
+ * Format: `pr:<positive integer>` (e.g. `pr:357`), or
+ * `pr:<component>@<integration>` (e.g. `pr:356@357`, T12671): component PR
+ * #356 merged into an integration branch that PR #357 landed on the default
+ * branch. The integration PR supplies the merge commit; the component PR
+ * supplies the task linkage and the changed files.
  *
  * @task T9764
  * @task T9838
@@ -206,6 +210,7 @@ export const decisionAtomSchema = z.object({
 export const prAtomSchema = z.object({
   kind: z.literal('pr'),
   prNumber: z.number().int().positive('pr atom requires a positive integer PR number'),
+  componentPrNumber: z.number().int().positive().optional(),
 });
 
 /**
@@ -214,13 +219,16 @@ export const prAtomSchema = z.object({
  * `qaPassed` only when the project opts in with `evidence.ciSatisfies`
  * (owner decision D11149).
  *
- * Format: `ci:<positive integer>` (e.g. `ci:357`).
+ * Format: `ci:<positive integer>` (e.g. `ci:357`), or
+ * `ci:<component>@<integration>` (e.g. `ci:356@357`, T12671): the integration
+ * PR's merge-commit CI, for a task linked through its component PR.
  *
  * @task T12634
  */
 export const ciAtomSchema = z.object({
   kind: z.literal('ci'),
   prNumber: z.number().int().positive('ci atom requires a positive integer PR number'),
+  componentPrNumber: z.number().int().positive().optional(),
 });
 
 /**
@@ -492,6 +500,9 @@ export const GATE_EVIDENCE_REQUIREMENTS: Readonly<
       ['decision', 'files'],
       ['decision', 'note'],
       ['pr', 'files'],
+      // T12689: a deletion-only PR (no bytes to hash). Contextual validation
+      // accepts this only when every change the PR made is a deletion.
+      ['pr', 'note'],
     ],
   },
   testsPassed: { oneOf: [['test-run'], ['tool'], ['ci']] },
@@ -771,6 +782,21 @@ export class EvidenceParseError extends Error {
  * @task T10337
  * @adr ADR-051
  */
+/**
+ * `<n>` or `<component>@<integration>` (T12671), each a positive integer.
+ * The integration PR is the atom's `prNumber`.
+ */
+function parsePrReference(
+  payload: string,
+): { prNumber: number; componentPrNumber?: number } | null {
+  const match = /^(\d+)(?:@(\d+))?$/.exec(payload);
+  if (!match) return null;
+  const first = Number(match[1]);
+  const second = match[2] === undefined ? null : Number(match[2]);
+  if (first <= 0 || (second !== null && (second <= 0 || second === first))) return null;
+  return second === null ? { prNumber: first } : { prNumber: second, componentPrNumber: first };
+}
+
 export function parseEvidenceString(raw: string): EvidenceAtom[] {
   if (!raw || typeof raw !== 'string') {
     throw new EvidenceParseError(
@@ -840,26 +866,16 @@ export function parseEvidenceString(raw: string): EvidenceAtom[] {
         atoms.push({ kind: 'decision', decisionId: payload });
         break;
       }
-      case 'pr': {
-        const prNumber = Number(payload);
-        if (!Number.isInteger(prNumber) || prNumber <= 0) {
-          throw new EvidenceParseError(
-            `pr atom requires a positive integer PR number, got "${payload}" in "${chunk}"`,
-            'Use format: pr:<number> e.g. pr:357',
-          );
-        }
-        atoms.push({ kind: 'pr', prNumber });
-        break;
-      }
+      case 'pr':
       case 'ci': {
-        const prNumber = Number(payload);
-        if (!Number.isInteger(prNumber) || prNumber <= 0) {
+        const ref = parsePrReference(payload);
+        if (!ref) {
           throw new EvidenceParseError(
-            `ci atom requires a positive integer PR number, got "${payload}" in "${chunk}"`,
-            'Use format: ci:<number> e.g. ci:357',
+            `${kind} atom requires a positive integer PR number, got "${payload}" in "${chunk}"`,
+            `Use format: ${kind}:<number> e.g. ${kind}:357, or ${kind}:<component>@<integration> e.g. ${kind}:356@357`,
           );
         }
-        atoms.push({ kind: 'ci', prNumber });
+        atoms.push(kind === 'pr' ? { kind: 'pr', ...ref } : { kind: 'ci', ...ref });
         break;
       }
       case 'loc-drop': {

package/src/index.ts

@@ -516,6 +516,7 @@ export type {
 // === Done planner: read-only `cleo done --plan` evidence plan (T12623, T12624) ===
 export type {
   ChangeSetDoc,
+  ChangeSetMergeState,
   ChangeSetPrCandidate,
   ChangeSetRootSource,
   ChangeSetSource,
@@ -2702,6 +2703,7 @@ export type {
   ScoreFactor,
   ScoreTaskContext,
   ScoreTaskInput,
+  ScoreTaskKey,
   ScoreTaskResult,
 } from './tools/score-task-priority.js';
 // === Transport (low-level wire protocol) ===
@@ -2889,11 +2891,15 @@ export type {
   ChoiceDecisionAnswer,
   ChoiceDecisionQuestion,
   DecisionAnswer,
+  DecisionBatchItem,
   DecisionInstructions,
   DecisionJsonValue,
   DecisionOutcome,
   DecisionOutcomeSource,
+  DecisionProviderCapabilities,
   DecisionProviderConfig,
+  DecisionProviderKind,
+  DecisionProviderUsage,
   DecisionQuestion,
   DecisionQuestionType,
   DecisionRequest,
@@ -2907,6 +2913,7 @@ export {
   choiceDecisionAnswerSchema,
   choiceDecisionQuestionSchema,
   DECISION_OUTCOME_SOURCES,
+  DECISION_PROVIDER_KINDS,
   DECISION_QUESTION_TYPES,
   DECISION_REQUEST_LIMITS,
   decisionAnswerSchema,
@@ -2914,14 +2921,32 @@ export {
   decisionOutcomeSchema,
   decisionOutcomeSourceSchema,
   decisionProviderConfigSchema,
+  decisionProviderKindSchema,
   decisionQuestionSchema,
   decisionQuestionTypeSchema,
   decisionRequestSchema,
   decisionStateSchema,
+  JEV_MINIMUM_CAPABILITIES,
+  LAYAHOST_BASE_URL,
+  LAYAHOST_DEFAULT_MODEL,
   noulDecisionAnswerSchema,
   noulDecisionQuestionSchema,
   scoreDecisionAnswerSchema,
   scoreDecisionQuestionSchema,
 } from './decide.js';
+// T12662: decision-site registry (the decision ladder as code).
+export type {
+  DecisionRung,
+  DecisionSiteActivity,
+  DecisionSiteDefinition,
+  DecisionSiteGoLive,
+  DecisionSiteModeValue,
+  DecisionSiteOwnerEscalation,
+  DecisionSiteQuestionType,
+  DecisionSiteSummary,
+  DecisionSitesListResult,
+  DecisionSiteTextClass,
+} from './decide-sites.js';
+export { DECISION_RUNGS, DECISION_SITE_MODES } from './decide-sites.js';
 
 export { isStorableTaskId, isTaskId, TASK_ID_REGEX, type TaskId } from './task-id.js';