@cleocode/contracts 2026.10.6 → 2026.10.7-rc.ci.674

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

@@ -30,12 +30,14 @@ import type { VerificationGate } from '../task.js';
 describe('EvidenceAtomSchema (T10337)', () => {
   it('EVIDENCE_ATOM_KINDS covers every discriminated union member (T12030)', () => {
     // Verify the shared constant is in sync with the zod discriminated union.
-    // The discriminated union keys are 'commit','files','test-run','tool','url',
-    // 'note','decision','pr','ci','loc-drop','callsite-coverage','satisfies'.
+    // The discriminated union keys are 'commit','files','test-run','qa-run',
+    // 'tool','url','note','decision','pr','ci','loc-drop','callsite-coverage',
+    // 'satisfies' ('qa-run': T13427).
     const expected = [
       'commit',
       'files',
       'test-run',
+      'qa-run',
       'tool',
       'url',
       'note',

package/src/acceptance-gate.ts

@@ -124,7 +124,8 @@ export interface TestGate extends GateBase {
   /** Arguments split explicitly (avoids shell-injection). */
   args?: string[];
   /**
-   * - `"pass"`: exit code 0 AND stdout contains no `FAIL|failing|Error:` pattern.
+   * - `"pass"`: exit code 0 AND stdout contains no `FAIL|failing|Error:` pattern, ignoring
+   *   summaries that report zero failures (`ℹ fail 0`, `# fail 0`, `0 failed`; T13511).
    * - `"exit0"`: exit code 0 only (permissive mode).
    */
   expect: 'pass' | 'exit0';

package/src/ask-enforce-hook.ts

@@ -0,0 +1,69 @@
+/**
+ * Ask-enforce Stop hook — shared types (T13420).
+ *
+ * The owner rule (CLEO-INJECTION.md universal protocol step 7) routes every
+ * owner question or decision through the harness ask tool. The ask-enforce
+ * hook runs when an agent's turn ends: if the final reply asks the owner
+ * something in prose and the turn made no ask-tool call, the hook blocks the
+ * stop and tells the agent to re-ask with its ask tool. The classifier lives
+ * in `@cleocode/core` (`harness/ask-enforce`); the provider wire formats and
+ * the entry point (`cleo hook ask-enforce`) in `@cleocode/cleo`.
+ *
+ * Design: `cleo docs fetch t13420-ask-enforce-stop-hook-design`.
+ *
+ * @task T13420
+ * @epic T13418
+ */
+
+/**
+ * How the hook treats a turn that ends in a prose owner question.
+ *
+ * - `block` — DEFAULT. Block the stop once per turn with the re-ask message.
+ * - `warn` — never block; surface the message as context only.
+ * - `off` — do nothing.
+ */
+export type AskEnforceMode = 'block' | 'warn' | 'off';
+
+/** What the classifier sees for one ended turn. */
+export interface AskEnforceInput {
+  /** The final assistant message of the turn (empty or absent: fail open). */
+  readonly lastAssistantText: string | null | undefined;
+  /** Tool names called since the last user message. */
+  readonly turnToolCalls: readonly string[];
+  /** Every tool name that counts as an ask-tool call (provider names, CAAMP union). */
+  readonly askToolNames: readonly string[];
+  /** The harness already re-prompted once from a stop hook in this turn. */
+  readonly stopHookActive?: boolean;
+  /** Blocks this hook already issued in this turn (loop guard for harnesses without `stopHookActive`). */
+  readonly blocksThisTurn?: number;
+}
+
+/**
+ * Which rule decided the verdict.
+ *
+ * - `no-text` — nothing to classify (fail open).
+ * - `asked` — the turn already called an ask tool.
+ * - `loop-guard` — the stop was already blocked once this turn.
+ * - `hitl-request` — the reply carries a `hitl.request` envelope (no-ask-tool fallback).
+ * - `clean` — no owner question in the reply's tail.
+ * - `prose-question` — a reader-directed question ends the reply.
+ * - `written-decision` — a request for an owner choice or approval without `?`.
+ */
+export type AskEnforceSignal =
+  | 'no-text'
+  | 'asked'
+  | 'loop-guard'
+  | 'hitl-request'
+  | 'clean'
+  | 'prose-question'
+  | 'written-decision';
+
+/** The classifier's answer for one ended turn. */
+export interface AskEnforceVerdict {
+  /** `block` only for `prose-question` / `written-decision`. */
+  readonly verdict: 'allow' | 'block';
+  /** The rule that decided. */
+  readonly signal: AskEnforceSignal;
+  /** The offending sentence, at most 160 characters (block only). */
+  readonly excerpt: string | null;
+}

package/src/dispatch/operations-registry.ts

@@ -100,6 +100,66 @@ export const OPERATIONS: OperationDef[] = [
       ],
     },
   },
+  {
+    gateway: 'mutate',
+    domain: 'tasks',
+    operation: 'req.replace',
+    description:
+      "Replace a typed requirement gate's definition in place, keeping its AC row and REQ-ID; the superseded gate is kept in AC history (T12988)",
+    tier: 1,
+    idempotent: true,
+    sessionRequired: true,
+    requiredParams: ['taskId', 'req', 'gate'],
+    params: [
+      requirementTaskParam,
+      {
+        name: 'req',
+        type: 'string',
+        required: true,
+        description: 'REQ-ID of the gate to replace',
+        cli: { positional: true },
+      },
+      {
+        name: 'gate',
+        type: 'string',
+        required: true,
+        description: 'Replacement AcceptanceGate JSON; its req must be absent or equal the REQ-ID',
+        cli: { flag: 'gate' },
+      },
+      {
+        name: 'reason',
+        type: 'string',
+        required: false,
+        description: 'Why the gate changes; required once the task is in a locked pipeline stage',
+        cli: { flag: 'reason' },
+      },
+    ],
+    inputSchema: {
+      operation: 'tasks.req.replace',
+      schema: {
+        type: 'object',
+        required: ['taskId', 'req', 'gate'],
+        additionalProperties: false,
+        properties: {
+          taskId: { type: 'string', minLength: 1 },
+          req: { type: 'string', minLength: 1 },
+          gate: { type: 'string', minLength: 1 },
+          reason: { type: 'string', minLength: 1 },
+        },
+      },
+      examples: [
+        {
+          name: 'repo-relative test gate',
+          value: {
+            taskId: 'T121',
+            req: 'PARTNER-121',
+            gate: '{"kind":"test","command":"pnpm","args":["--filter","app","exec","vitest","run","src/a.test.ts"],"expect":"pass","description":"Task tests pass","req":"PARTNER-121"}',
+            reason: 'gate pointed at a removed worktree',
+          },
+        },
+      ],
+    },
+  },
   {
     gateway: 'query',
     domain: 'tasks',
@@ -1849,6 +1909,14 @@ export const OPERATIONS: OperationDef[] = [
         required: false,
         description: 'Actor attribution recorded on each gate result',
       },
+      {
+        name: 'req',
+        type: 'string',
+        required: false,
+        description:
+          'Comma-separated REQ-IDs: run and cache only these typed gates; the others are not run (T13486)',
+        cli: { flag: 'req' },
+      },
     ] satisfies ParamDef[],
   },
   // check.archive.stats incoming from admin (T5615)
@@ -8510,6 +8578,56 @@ export const OPERATIONS: OperationDef[] = [
       },
     ],
   },
+  // ── docs.doctor (T13447 — Epic T13340 / Saga T13339) ──────────────────────
+  {
+    gateway: 'query',
+    domain: 'docs',
+    operation: 'doctor',
+    description:
+      'docs.doctor (query) — docs store health diagnostics (dry-run): dangling local-file ' +
+      'pointers, docVersion skew vs the audit log, empty topics/related_tasks provenance, ' +
+      'docs_wikilinks drift, legacy store surfaces, stale drafts. Reports a repair plan.',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [
+      {
+        name: 'olderThanDays',
+        type: 'number' as const,
+        required: false,
+        description: 'Age threshold in days for the stale-drafts check (default 30)',
+      },
+    ],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'docs',
+    operation: 'doctor',
+    description:
+      'docs.doctor (mutate) — apply the docs doctor repairs: set docVersion from the audit ' +
+      'log, backfill topics/related_tasks from content, archive dangling local-file rows, ' +
+      'rebuild docs_wikilinks. The dispatch layer creates a fresh backup (cleo backup add ' +
+      'path) and requires its receipt before any write.',
+    tier: 1,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [
+      {
+        name: 'apply',
+        type: 'boolean' as const,
+        required: false,
+        description: 'Execute repairs (default false — dry-run plan only)',
+      },
+      {
+        name: 'olderThanDays',
+        type: 'number' as const,
+        required: false,
+        description: 'Age threshold in days for the stale-drafts check (default 30)',
+      },
+    ],
+  },
   // ── docs.generate (T798) ─────────────────────────────────────────────────
   {
     gateway: 'query',

package/src/done-plan.ts

@@ -67,6 +67,7 @@ export type DonePlanBlockerCode =
   | 'tool-failed'
   | 'typed-gate-failed'
   | 'test-run-needed'
+  | 'qa-run-needed'
   | 'ac-mapping-needed'
   | 'manual-gate'
   | 'epic-rollup'

package/src/evidence-atom-schema.ts

@@ -57,6 +57,7 @@ export const EVIDENCE_ATOM_KINDS = [
   'commit',
   'files',
   'test-run',
+  'qa-run',
   'tool',
   'url',
   'note',
@@ -126,6 +127,22 @@ export const testRunAtomSchema = z.object({
   path: z.string().min(1, 'test-run atom requires a non-empty path'),
 });
 
+/**
+ * `qa-run:<path>` atom — path to a JSON receipt of a native typecheck or lint
+ * run (T13427): `{kind, command, exitCode, diagnostics: {errors}, roots,
+ * startTime?, tool?: {name, version}}`.
+ *
+ * Format: `qa-run:<absolute or project-relative path>`. The runtime validator
+ * requires exit 0 and zero errors, binds the receipt to the change (fresh,
+ * covering every changed code path) and pins the tree hash.
+ *
+ * @task T13427
+ */
+export const qaRunAtomSchema = z.object({
+  kind: z.literal('qa-run'),
+  path: z.string().min(1, 'qa-run atom requires a non-empty path'),
+});
+
 /**
  * `tool:<name>` atom — runs a project-resolved canonical tool and accepts
  * exit-code 0.
@@ -391,6 +408,7 @@ export const satisfiesAtomSchema = z.object({
  *   - `commit`             — git commit SHA (T832)
  *   - `files`              — touched file paths (T832)
  *   - `test-run`           — structured test runner JSON (T832)
+ *   - `qa-run`             — native typecheck/lint receipt JSON (T13427)
  *   - `tool`               — project-resolved tool exit code (T832 / T1534)
  *   - `url`                — soft external pointer (T832)
  *   - `note`               — free-form note (T832)
@@ -408,6 +426,7 @@ export const EvidenceAtomSchema = z.discriminatedUnion('kind', [
   commitAtomSchema,
   filesAtomSchema,
   testRunAtomSchema,
+  qaRunAtomSchema,
   toolAtomSchema,
   urlAtomSchema,
   noteAtomSchema,
@@ -506,7 +525,7 @@ export const GATE_EVIDENCE_REQUIREMENTS: Readonly<
     ],
   },
   testsPassed: { oneOf: [['test-run'], ['tool'], ['ci']] },
-  qaPassed: { oneOf: [['tool'], ['ci']] },
+  qaPassed: { oneOf: [['tool'], ['ci'], ['qa-run']] },
   documented: { oneOf: [['files'], ['url']] },
   securityPassed: { oneOf: [['tool'], ['note']] },
   cleanupDone: { oneOf: [['note']] },
@@ -565,6 +584,7 @@ const ATOM_EXAMPLES: Readonly<Record<EvidenceAtomKind, string>> = Object.freeze(
   commit: 'commit:<sha>',
   files: 'files:path/a.ts,path/b.ts',
   'test-run': 'test-run:/tmp/vitest-out.json',
+  'qa-run': 'qa-run:/tmp/typecheck-receipt.json',
   tool: 'tool:test',
   url: 'url:https://example.com/docs',
   note: 'note:<short description>',
@@ -847,6 +867,9 @@ export function parseEvidenceString(raw: string): EvidenceAtom[] {
       case 'test-run':
         atoms.push({ kind: 'test-run', path: payload });
         break;
+      case 'qa-run':
+        atoms.push({ kind: 'qa-run', path: payload });
+        break;
       case 'tool':
         atoms.push({ kind: 'tool', tool: payload });
         break;

package/src/git-hooks.ts

@@ -0,0 +1,43 @@
+/** Hash-guarded Git hook installation and recovery contracts. */
+import { z } from 'zod';
+
+/** Canonical names of the three shipped Git checks. */
+export const CLEO_GIT_HOOK_NAMES = ['commit-msg', 'pre-commit', 'pre-push'] as const;
+
+/** One recoverable managed Git hook change. */
+export const GitHookChangeSchema = z.object({
+  name: z.enum(CLEO_GIT_HOOK_NAMES),
+  before: z.string().nullable(),
+  beforeMode: z.number().int().min(0).max(0o777).nullable(),
+  afterHash: z.string().regex(/^[a-f0-9]{64}$/),
+});
+/** A receipt scoped to the effective Git hook directory. */
+export const GitHookInstallReceiptSchema = z.object({
+  schemaVersion: z.literal(1),
+  hooksDir: z.string(),
+  changes: z.array(GitHookChangeSchema),
+});
+/** One managed change with its recovery image. */
+export type GitHookChange = z.infer<typeof GitHookChangeSchema>;
+/** Installation image used only after matching the current content hash. */
+export type GitHookInstallReceipt = z.infer<typeof GitHookInstallReceiptSchema>;
+
+/** Exact hashes of historical shipped templates; marker text is insufficient. */
+export const GitHookLegacyHashesSchema = z.record(
+  z.string(),
+  z.array(z.string().regex(/^[a-f0-9]{64}$/)),
+);
+
+/** Explicit installer controls shared by SDK wrappers and CLI delivery. */
+export interface GitHookInstallOptions {
+  /** Override shipped template location. */
+  templatesDir?: string;
+  /** Deprecated compatibility flag; never bypasses ownership or tracked-path safety. */
+  force?: boolean;
+  /** Preview without filesystem mutations. */
+  dryRun?: boolean;
+  /** Restore matching local installation images. */
+  rollbackReceipt?: GitHookInstallReceipt;
+  /** Explicitly permit writes into an effective hooksPath inside the working tree. */
+  allowTrackedHooksPath?: boolean;
+}

package/src/index.ts

@@ -85,6 +85,13 @@ export type {
   CycleTimeDistribution,
   CycleTimePercentiles,
 } from './archive.js';
+// === Ask-enforce Stop hook (T13420 / Epic T13418) ===
+export type {
+  AskEnforceInput,
+  AskEnforceMode,
+  AskEnforceSignal,
+  AskEnforceVerdict,
+} from './ask-enforce-hook.js';
 // === Attachment Types ===
 export type {
   Attachment,
@@ -613,6 +620,7 @@ export {
   noteAtomSchema,
   parseEvidenceString,
   prAtomSchema,
+  qaRunAtomSchema,
   SATISFIES_TASK_ID_REGEX,
   SATISFIES_VERSION_PIN_REGEX,
   satisfiesAtomSchema,
@@ -3158,6 +3166,9 @@ export {
   type CloudLeaseReleaseResult,
   type CloudPushResult,
   type CloudRestoreResult,
+  type CloudSyncPushEnableResult,
+  type CloudSyncResult,
+  type CloudSyncStreamResult,
   type CloudVaultLease,
   type CloudVaultScope,
   type CloudVaultSnapshot,

package/src/nexus-account.ts

@@ -101,6 +101,16 @@ export const NEXUS_ACCOUNT_ERROR_CODES = [
   'E_NEXUS_VAULT_STORE_BUSY',
   /** A project restore target already holds a different project. */
   'E_NEXUS_VAULT_TARGET_OCCUPIED',
+  // Change-journal push (`cleo sync enable push`, T12343 S4-1b).
+  /** The store is not fit to reach genesis (a precondition failed); nothing was cut. */
+  'E_NEXUS_SYNC_REFUSED',
+  /**
+   * Another device already started this stream's change journal: this store restores its journal
+   * checkpoint, then joins the stream (T12999), never writing a second genesis.
+   */
+  'E_NEXUS_SYNC_STREAM_JOURNALED',
+  /** `cleo cloud sync` found no stream with `sync.push` or `sync.pull` on (`cleo sync enable`). */
+  'E_SYNC_DISABLED',
   // Projects by name (`cleo cloud restore <name>`, T13102).
   /** No project of the account has that name, label or id. */
   'E_NEXUS_PROJECT_NOT_FOUND',

package/src/nexus-cloud.ts

@@ -614,6 +614,20 @@ export interface CloudStatusUndoBudget {
   readonly exceededAt: string | null;
 }
 
+/**
+ * The pull's seen-transaction ledger (`_sync_seen_txn`, T13317). The cloud
+ * pull prunes each origin's rows below its staged `local_seq` floor (T13318);
+ * a pruned transaction delivered again is refused, never applied twice.
+ */
+export interface CloudStatusSeenTxns {
+  /** Rows held, every stream. */
+  readonly rows: number;
+  /** Estimated bytes: the stored text and integer payload, without SQLite page overhead. */
+  readonly bytes: number;
+  /** Rows per stream. */
+  readonly byStream: Readonly<Record<string, number>>;
+}
+
 export interface CloudStatusSyncStream {
   /** Which store. */
   readonly scope: 'project' | 'global';
@@ -639,6 +653,8 @@ export interface CloudStatusSyncStream {
   readonly held: CloudStatusHeld;
   /** Undo held against its budget (§3.5 Rule 2, D5). */
   readonly undo: CloudStatusUndoBudget;
+  /** The seen-transaction ledger's size; it grows until pruning has a proven floor (T13317). */
+  readonly seenTxns: CloudStatusSeenTxns;
   /** Sealed ops not yet handed to the outbox for sending. */
   readonly unsentOps: CloudSyncFact<number>;
   /** The last sequence this store pushed to the server. */

package/src/nexus-vault.ts

@@ -211,6 +211,76 @@ export interface CloudPushResult {
   warnings: CloudWarning[];
 }
 
+/** `cleo sync enable push`: the stream's genesis cut and its genesis checkpoint (T12343 S4-1b). */
+export interface CloudSyncPushEnableResult {
+  apiUrl: string;
+  scope: CloudVaultScope;
+  streamId: string;
+  /**
+   * `enabled`: the cut was recorded and its genesis checkpoint stored; `resumed`: a cut recorded
+   * by an earlier run whose checkpoint push failed was pushed now; `already`: push was already on;
+   * `joined`: this store holds the stream's journal checkpoint another device cut, and now pushes its
+   * own writes and pulls the stream's after it, with no genesis of its own (T13312).
+   */
+  status: 'enabled' | 'resumed' | 'already' | 'joined';
+  /** The genesis cut: the highest capture seq the checkpoint carries. */
+  cut: number;
+  /** Transactions sealed before the cut, folded into the checkpoint, and rows given genesis row meta. */
+  sealed: number;
+  folded: number;
+  baselined: Record<string, number>;
+  /** The genesis checkpoint (null when `already`). */
+  snapshot: CloudVaultSnapshot | null;
+  /** The delta segment appended so the counts reconcile with the parent, if one was needed. */
+  deltaSegmentSeq: number | null;
+  /** The replicaSeq this replica's first journal segment follows (null: it starts at 0). */
+  replicaSeqFloor: number | null;
+  warnings: CloudWarning[];
+}
+
+/** One stream of `cleo cloud sync` (T12996). */
+export interface CloudSyncStreamResult {
+  scope: CloudVaultScope;
+  streamId: string | null;
+  /**
+   * `synced`: pushed and pulled what was enabled; `disabled`: neither `sync.push` nor `sync.pull` is on;
+   * `paused`: push paused for a device clock ahead of the server's; `not-attached`: this machine has no
+   * store on that stream; `refused`: a precondition or the server refused (see `refused`); `failed`: an
+   * error stopped this stream (see `refused`); the other streams still synced.
+   */
+  status: 'synced' | 'disabled' | 'paused' | 'not-attached' | 'refused' | 'failed';
+  /** Why this stream did not sync fully, or null. */
+  refused: string | null;
+  /**
+   * Legs with nothing to do, not failures: a flag off, or push before this store has its own genesis
+   * (a store that only pulls).
+   */
+  skipped: string[];
+  /** Transactions sealed, segments persisted, segments the server stored (`duplicates` of them retries). */
+  sealed: number;
+  built: number;
+  sent: number;
+  duplicates: number;
+  /** Segments received, transactions staged, re-deliveries skipped. */
+  received: number;
+  staged: number;
+  redelivered: number;
+  /** Transactions applied; still held (pending, clock skew, or a newer schema); in conflict. */
+  applied: number;
+  held: number;
+  conflicts: number;
+  /** The stream position this store has staged up to, and the server's head (null when not pulled). */
+  after: number | null;
+  head: number | null;
+}
+
+/** `cleo cloud sync` (T12996): seal, push, pull and apply each attached stream. */
+export interface CloudSyncResult {
+  apiUrl: string;
+  streams: CloudSyncStreamResult[];
+  warnings: CloudWarning[];
+}
+
 /** `cleo cloud pull` / `cleo cloud restore`. */
 export interface CloudRestoreResult {
   apiUrl: string;
@@ -372,7 +442,7 @@ export interface CloudConflict {
   columns: string[];
   /** The typed rule, guard message or invariant, when there is one. */
   rule: string | null;
-  /** What happened to the incoming op: `incoming-applied`, `incoming-dropped`, `row-deleted`, `op-voided`. */
+  /** What happened to the incoming op: `incoming-applied`, `incoming-dropped`, `row-deleted`, `op-voided`, `op-held`. */
   resolution: string;
   opHlc: string;
   localHlc: string | null;

package/src/operations/docs.ts

@@ -899,6 +899,90 @@ export interface DocsSupersedeResult {
   reason?: string;
 }
 
+// --------------------------------------------------------------------------
+// docs.doctor — store health diagnostics + safe repairs (T13447)
+// --------------------------------------------------------------------------
+
+/**
+ * Parameters for `docs.doctor`.
+ *
+ * Dry-run by default; `apply: true` executes the repairs (the dispatch layer
+ * creates a fresh backup first and hands the receipt to core — callers never
+ * pass one).
+ *
+ * @task T13447 (Epic T13340 / Saga T13339)
+ */
+export interface DocsDoctorParams {
+  /** Execute repairs instead of producing a dry-run plan. Default false. */
+  apply?: boolean;
+  /** Age threshold (days) for the `stale-drafts` diagnostic. Default 30. */
+  olderThanDays?: number;
+}
+
+/**
+ * One `docs.doctor` diagnostic class in the report.
+ *
+ * @task T13447
+ */
+export interface DocsDoctorDiagnostic {
+  /** Which check produced this entry. */
+  kind:
+    | 'dangling-pointers'
+    | 'doc-version-skew'
+    | 'empty-provenance'
+    | 'wikilinks-drift'
+    | 'legacy-store-present'
+    | 'stale-drafts';
+  /** `error` should be fixed promptly; `info` is observational. */
+  severity: 'info' | 'warn' | 'error';
+  /** Total offenders found (may exceed `items.length`). */
+  count: number;
+  /** Capped per-item detail. */
+  items: ReadonlyArray<Record<string, unknown>>;
+  /** True when `count` exceeded the detail cap. */
+  truncated: boolean;
+}
+
+/**
+ * One planned or executed `docs.doctor` repair step.
+ *
+ * @task T13447
+ */
+export interface DocsDoctorRepairAction {
+  /** Diagnostic class this repair addresses. */
+  kind: DocsDoctorDiagnostic['kind'];
+  /** Machine-readable action verb (e.g. `set-doc-version`). */
+  action: string;
+  /** False on a dry run (the action is a plan, not a write). */
+  applied: boolean;
+  /** Doc slug the action touched, when row-scoped. */
+  slug?: string;
+  /** Attachment id the action touched, when row-scoped. */
+  attachmentId?: string;
+  /** Human-readable detail (old→new values, derived counts, …). */
+  detail: string;
+}
+
+/**
+ * Result of `docs.doctor`.
+ *
+ * @task T13447
+ */
+export interface DocsDoctorResult {
+  /** True when repairs were written (`apply: true`). */
+  applied: boolean;
+  /** Age threshold used for the `stale-drafts` check. */
+  olderThanDays: number;
+  /** Backup receipt that authorised this run (null on dry runs). */
+  backupReceiptPath: string | null;
+  /** All six diagnostics, in declaration order. */
+  diagnostics: readonly DocsDoctorDiagnostic[];
+  /** Repair plan (dry run) or executed repairs (apply). */
+  repairs: readonly DocsDoctorRepairAction[];
+  /** One-line human summary. */
+  summary: string;
+}
+
 // ============================================================================
 // Discriminated Union (DocsOps)
 // ============================================================================
@@ -921,7 +1005,8 @@ export type DocsOps =
   | { op: 'docs.add'; params: DocsAddParams; result: DocsAddResult }
   | { op: 'docs.remove'; params: DocsRemoveParams; result: DocsRemoveResult }
   | { op: 'docs.update'; params: DocsUpdateParams; result: DocsUpdateResult }
-  | { op: 'docs.supersede'; params: DocsSupersedeParams; result: DocsSupersedeResult };
+  | { op: 'docs.supersede'; params: DocsSupersedeParams; result: DocsSupersedeResult }
+  | { op: 'docs.doctor'; params: DocsDoctorParams; result: DocsDoctorResult };
 
 /**
  * Enumeration of all docs domain operation names.
@@ -938,4 +1023,5 @@ export type DocsOp =
   | 'docs.add'
   | 'docs.remove'
   | 'docs.update'
-  | 'docs.supersede';
+  | 'docs.supersede'
+  | 'docs.doctor';

package/src/operations/orchestrate.ts

@@ -561,8 +561,22 @@ export interface OrchestrateSpawnResult {
    * @task T963
    */
   prompt: string;
-  /** Agent id the spawn is routed to. @task T963 */
+  /**
+   * The spawned agent's identity: the same id as `worktreeEnv.CLEO_AGENT_ID`,
+   * its per-agent session's handle (`agent-<task>`) and the worktree lock
+   * holder. Before T13494 this field carried the classifier's persona.
+   * @task T963
+   * @task T13494
+   */
   agentId: string;
+  /**
+   * The agent profile the classifier routed the task to (e.g.
+   * `project-security-worker`, `cleo-subagent`); mirrors
+   * `meta.classify.agentId`. It names what the prompt is written for, not who
+   * runs it.
+   * @task T13494
+   */
+  persona: string;
   /** Role the agent will execute as (`orchestrator` | `lead` | `worker`). @task T963 */
   role: string;
   /** Tier of the rendered prompt (0/1/2). @task T963 */

package/src/operations/validate.ts

@@ -228,6 +228,11 @@ export interface ValidateGateParams {
    * none; a gate without a fresh cached pass refuses with `E_GATE_NOT_CACHED`.
    */
   noRun?: boolean;
+  /**
+   * `cleo verify --run --req A,B` (T13486): run and cache only the typed gates
+   * with these REQ-IDs (comma-separated); the others are not run.
+   */
+  req?: string;
 }
 export interface ValidateGateResult {
   taskId: string;