@cleocode/contracts 2026.5.114 → 2026.5.121

package/src/dispatch/operations-registry.ts

@@ -2335,6 +2335,41 @@ export const OPERATIONS: OperationDef[] = [
       },
     ] satisfies ParamDef[],
   },
+  {
+    gateway: 'mutate',
+    domain: 'tasks',
+    operation: 'relates.remove',
+    description:
+      'tasks.relates.remove (mutate) — delete a relation between two tasks. Pass `type` to scope deletion to a single relation kind; omit to remove any type.',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['taskId', 'relatedId'],
+    params: [
+      {
+        name: 'taskId',
+        type: 'string',
+        required: true,
+        description: 'Source task ID',
+        cli: { positional: true },
+      },
+      {
+        name: 'relatedId',
+        type: 'string',
+        required: true,
+        description: 'Target task ID to remove the relation to',
+        cli: { positional: true },
+      },
+      {
+        name: 'type',
+        type: 'string',
+        required: false,
+        description:
+          'Optional relation type (blocks|related|duplicates|absorbs|fixes|extends|supersedes). Omit to remove any type.',
+        cli: { flag: 'type' },
+      },
+    ] satisfies ParamDef[],
+  },
   // === saga sub-domain (ADR-073 — above-epic grouping tier) ===
   {
     gateway: 'mutate',
@@ -6771,6 +6806,40 @@ export const OPERATIONS: OperationDef[] = [
       },
     ],
   },
+  // ── docs.supersede (T10162) ──────────────────────────────────────────────
+  {
+    gateway: 'mutate',
+    domain: 'docs',
+    operation: 'supersede',
+    description:
+      'docs.supersede (mutate) — atomically flip an older doc to `superseded` and link both rows via the supersedes/superseded_by self-FK pointers (T10162 · Saga T9855)',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['oldSlug', 'newSlug'],
+    params: [
+      {
+        name: 'oldSlug',
+        type: 'string' as const,
+        required: true,
+        description: 'Slug of the doc being replaced',
+        cli: { positional: true },
+      },
+      {
+        name: 'newSlug',
+        type: 'string' as const,
+        required: true,
+        description: 'Slug of the doc that replaces oldSlug',
+        cli: { positional: true },
+      },
+      {
+        name: 'reason',
+        type: 'string' as const,
+        required: false,
+        description: 'Optional human-readable reason carried back on the response',
+      },
+    ],
+  },
   // ── docs.generate (T798) ─────────────────────────────────────────────────
   {
     gateway: 'query',
@@ -6797,6 +6866,61 @@ export const OPERATIONS: OperationDef[] = [
       },
     ],
   },
+  // ── docs.update (T10161 — Epic T10157 / Saga T9855) ──────────────────────
+  {
+    gateway: 'mutate',
+    domain: 'docs',
+    operation: 'update',
+    description:
+      'docs.update (mutate) — replace blob content for an existing slug while preserving the slug. ' +
+      'New sha256 + new attachment row; the old row stays reachable by ID for history. ' +
+      'NO supersession edge (use `cleo docs supersede` for that). ' +
+      'Audit log entry appended to .cleo/audit/docs-versioning.jsonl (squashed within a 5-min window).',
+    tier: 1,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['slug'],
+    params: [
+      {
+        name: 'slug',
+        type: 'string' as const,
+        required: true,
+        description: 'Slug of the existing attachment to update',
+      },
+      {
+        name: 'file',
+        type: 'string' as const,
+        required: false,
+        description: 'Path to a local file containing the new content',
+      },
+      {
+        name: 'content',
+        type: 'string' as const,
+        required: false,
+        description: 'Inline UTF-8 content (mutually exclusive with file)',
+      },
+      {
+        name: 'message',
+        type: 'string' as const,
+        required: false,
+        description: 'One-line summary describing the change (recorded in the audit log)',
+      },
+      {
+        name: 'status',
+        type: 'string' as const,
+        required: false,
+        description:
+          'Override the new lifecycle status. Defaults to "draft" on every update. ' +
+          'Valid: draft|proposed|accepted|superseded|archived|deprecated.',
+      },
+      {
+        name: 'attachedBy',
+        type: 'string' as const,
+        required: false,
+        description: 'Agent identity that performed the update (defaults to "human")',
+      },
+    ],
+  },
   // ── playbook.* HITL CLI surface (T935) ───────────────────────────────────
   {
     gateway: 'mutate',
@@ -7505,6 +7629,37 @@ export const OPERATIONS: OperationDef[] = [
     ] satisfies ParamDef[],
   },
 
+  // release query: validate-changelog (T9937 / Saga T9862 — canonical CHANGELOG
+  // header validator that replaces the brittle inline grep step in
+  // .github/workflows/release.yml). Read-only — exposed only under the query
+  // gateway because no DB or filesystem mutation occurs.
+  {
+    gateway: 'query',
+    domain: 'release',
+    operation: 'validate-changelog',
+    description:
+      'release.validate-changelog (query) — validate that CHANGELOG.md contains the canonical `## [VERSION]` header per ADR-028 §2.5. Replaces the brittle inline grep in .github/workflows/release.yml (T9937 / Saga T9862).',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['version'],
+    params: [
+      {
+        name: 'version',
+        type: 'string',
+        required: true,
+        description: 'Release version (accepts v2026.5.94 or 2026.5.94)',
+        cli: { positional: true },
+      },
+      {
+        name: 'changelogPath',
+        type: 'string',
+        required: false,
+        description: 'Override the CHANGELOG file path (default: <projectRoot>/CHANGELOG.md)',
+      },
+    ] satisfies ParamDef[],
+  },
+
   // ---------------------------------------------------------------------------
   // Provenance domain — `cleo provenance` CLI surface (T9528 · Phase 2 of T9493)
   // ---------------------------------------------------------------------------

package/src/evidence-atom-schema.ts

@@ -332,14 +332,25 @@ export const GATE_EVIDENCE_REQUIREMENTS: Readonly<
  * Result of {@link validateEvidenceForGate}.
  *
  * Success carries no extra payload (the caller already holds the atom list).
- * Failure carries a human-readable message in the legacy
- * `Gate '<gate>' requires evidence: [<combo>] OR [<combo>]` format so error
- * surfaces (E_EVIDENCE_INSUFFICIENT) read identically across the CLI and any
- * client-side validator built on top of this schema.
+ * Failure carries:
+ *   - {@link EvidenceValidationFailure.message} — the legacy single-line
+ *     `Gate '<gate>' requires evidence: [<combo>] OR [<combo>]` format,
+ *     preserved byte-for-byte for backward-compat with surfaces and tests
+ *     that match against it.
+ *   - {@link EvidenceValidationFailure.hint} — a richer, multi-line,
+ *     example-bearing remediation hint suitable for CLI `fix:` surfaces.
+ *     Added by T9949 so `E_EVIDENCE_INSUFFICIENT` errors point clearly at
+ *     the alternative atom the caller needs (e.g. "this gate requires
+ *     real proof — note: alone is not accepted; use commit+files,
+ *     commit+note, or pr instead").
  */
-export type EvidenceValidationResult =
-  | { readonly ok: true }
-  | { readonly ok: false; readonly message: string };
+export interface EvidenceValidationFailure {
+  readonly ok: false;
+  readonly message: string;
+  readonly hint: string;
+}
+
+export type EvidenceValidationResult = { readonly ok: true } | EvidenceValidationFailure;
 
 /**
  * Format the satisfying-combinations spec for a gate as the legacy
@@ -354,6 +365,114 @@ export function formatGateRequirement(gate: VerificationGate): string {
   return requirement.oneOf.map((set) => `[${set.join(' AND ')}]`).join(' OR ');
 }
 
+/**
+ * Example `--evidence` strings for each atom kind. Used by
+ * {@link formatGateRequirementHint} to render copy-pasteable remediation
+ * commands in CLI error surfaces.
+ *
+ * @task T9949
+ */
+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',
+  tool: 'tool:test',
+  url: 'url:https://example.com/docs',
+  note: 'note:<short description>',
+  decision: 'decision:D-arch-001',
+  pr: 'pr:357',
+  'loc-drop': 'loc-drop:<fromLines>:<toLines>',
+  'callsite-coverage': 'callsite-coverage:<symbolName>:<relativeSourcePath>',
+});
+
+/**
+ * Render a satisfying atom combination as a copy-pasteable `--evidence`
+ * string fragment, e.g. `['commit', 'files']` → `commit:<sha>;files:path/a.ts,path/b.ts`.
+ *
+ * @internal
+ */
+function renderCombinationAsEvidence(combination: ReadonlyArray<EvidenceAtomKind>): string {
+  return combination.map((kind) => ATOM_EXAMPLES[kind]).join(';');
+}
+
+/**
+ * Produce a multi-line, example-bearing remediation hint for a gate.
+ *
+ * Designed for CLI `fix:` surfaces so `E_EVIDENCE_INSUFFICIENT` errors point
+ * the caller at the specific alternative atom shape they need. The hint lists
+ * every satisfying combination as a copy-pasteable `cleo verify` invocation
+ * plus a note-specific clarification when the gate does NOT accept `note:`
+ * alone.
+ *
+ * The motivating bug (T9949) was that note-only deliverables (decision-only
+ * tasks, deletion-only refactors) hit `E_EVIDENCE_INSUFFICIENT` with the
+ * legacy single-line error and had to consult ADR-051 to figure out which
+ * additional atom kind the gate required. The richer hint inlines the answer.
+ *
+ * @param gate - Verification gate the hint is for.
+ * @returns Multi-line remediation hint suitable for an `engineError({fix:})`
+ *   surface. Always ends in a clarifying sentence about whether `note:` alone
+ *   is accepted for the gate.
+ *
+ * @example
+ * ```ts
+ * formatGateRequirementHint('implemented');
+ * // "Gate 'implemented' requires programmatic evidence. Use ONE of:
+ * //   - cleo verify T#### --gate implemented --evidence 'commit:<sha>;files:path/a.ts,path/b.ts'
+ * //   - cleo verify T#### --gate implemented --evidence 'commit:<sha>;note:<short description>'
+ * //   - cleo verify T#### --gate implemented --evidence 'decision:D-arch-001;files:path/a.ts,path/b.ts'
+ * //   - cleo verify T#### --gate implemented --evidence 'decision:D-arch-001;note:<short description>'
+ * //   - cleo verify T#### --gate implemented --evidence 'pr:357'
+ * // Note: 'note:' alone is NOT accepted for this gate — pair it with 'commit:' or 'decision:'."
+ * ```
+ *
+ * @task T9949
+ * @adr ADR-051 §2.3
+ */
+export function formatGateRequirementHint(gate: VerificationGate): string {
+  const requirement = GATE_EVIDENCE_REQUIREMENTS[gate];
+  if (!requirement) {
+    // Unknown gate — match validateEvidenceForGate's defensive default.
+    return `Gate '${gate}' has no documented evidence requirements.`;
+  }
+
+  const lines: string[] = [
+    `Gate '${gate}' requires programmatic evidence. Use ONE of:`,
+    ...requirement.oneOf.map(
+      (combo) =>
+        `  - cleo verify T#### --gate ${gate} --evidence '${renderCombinationAsEvidence(combo)}'`,
+    ),
+  ];
+
+  // Note-specific clarification — T9949's headline pain point.
+  // The gate accepts note: alone IFF some single-element combination is ['note'].
+  const noteAloneAccepted = requirement.oneOf.some(
+    (combo) => combo.length === 1 && combo[0] === 'note',
+  );
+  if (noteAloneAccepted) {
+    lines.push(`Note: 'note:' alone IS accepted for this gate (waiver-style evidence).`);
+  } else {
+    // Surface every alternative pairing involving note for at-a-glance routing.
+    const notePairings = requirement.oneOf.filter(
+      (combo) => combo.length > 1 && combo.includes('note'),
+    );
+    if (notePairings.length > 0) {
+      const partners = Array.from(
+        new Set(notePairings.flatMap((combo) => combo.filter((k) => k !== 'note'))),
+      ).map((k) => `'${k}:'`);
+      lines.push(
+        `Note: 'note:' alone is NOT accepted for this gate — pair it with ${partners.join(' or ')}.`,
+      );
+    } else {
+      lines.push(
+        `Note: 'note:' is NOT accepted for this gate (even when paired). See ADR-051 for the full grammar.`,
+      );
+    }
+  }
+
+  return lines.join('\n');
+}
+
 /**
  * Check whether a set of parsed atoms satisfies the requirement spec for
  * `gate`.
@@ -401,6 +520,11 @@ export function validateEvidenceForGate(
   return {
     ok: false,
     message: `Gate '${gate}' requires evidence: ${formatGateRequirement(gate)}`,
+    // T9949: rich, example-bearing remediation hint suitable for CLI `fix:`.
+    // Always populated alongside `message` so consumers can choose between
+    // the legacy single-line surface and the multi-line hint without re-
+    // computing the spec.
+    hint: formatGateRequirementHint(gate),
   };
 }
 

package/src/index.ts

@@ -475,6 +475,7 @@ export {
 export type {
   EvidenceAtom as EvidenceAtomInput,
   EvidenceAtomKind,
+  EvidenceValidationFailure,
   EvidenceValidationResult,
   GateEvidenceRequirement,
 } from './evidence-atom-schema.js';
@@ -486,6 +487,7 @@ export {
   EvidenceParseError,
   filesAtomSchema,
   formatGateRequirement,
+  formatGateRequirementHint,
   GATE_EVIDENCE_REQUIREMENTS,
   locDropAtomSchema,
   noteAtomSchema,

package/src/operations/docs.ts

@@ -1,15 +1,17 @@
 /**
- * Docs Domain Operations Contract (5 operations)
+ * Docs Domain Operations Contract (7 operations)
  *
  * Query operations: 3
- * Mutate operations: 2
+ * Mutate operations: 4
  *
  * Docs domain handles attachment management and document generation via `cleo docs`:
- *   - add     — attach a local file or URL to a CLEO owner entity (task, session, observation)
- *   - list    — list attachments for an owner entity
- *   - generate — generate llms.txt summary for a task/epic, optionally attach as blob
- *   - fetch   — retrieve attachment bytes and metadata by ID or SHA-256
- *   - remove  — remove an attachment ref; purges blob when refCount hits zero
+ *   - add        — attach a local file or URL to a CLEO owner entity (task, session, observation)
+ *   - list       — list attachments for an owner entity
+ *   - generate   — generate llms.txt summary for a task/epic, optionally attach as blob
+ *   - fetch      — retrieve attachment bytes and metadata by ID or SHA-256
+ *   - remove     — remove an attachment ref; purges blob when refCount hits zero
+ *   - update     — UPDATE-in-place via slug (T10161)
+ *   - supersede  — atomically flip an older doc to `superseded` and link it to its successor (T10162)
  *
  * Owner type is auto-detected from the owner ID prefix:
  *   T###        → 'task'
@@ -398,6 +400,15 @@ export interface DocsAddParams {
    * @task T9636 (T-DOCS-SLUG-1)
    */
   slug?: string;
+  /**
+   * Optional human-readable title — used to derive the kebab-slug tail when
+   * auto-allocating an ADR slug. REQUIRED when `type === 'adr'` AND `slug`
+   * is omitted; ignored otherwise. The allocator slugifies the title via
+   * the shared kebabize helper.
+   *
+   * @task T10360 (closes T10153)
+   */
+  title?: string;
   /**
    * Optional taxonomy classification. Must match one of
    * {@link DOCS_TYPE_VALUES}; an invalid value returns `E_INVALID_TYPE`.
@@ -447,6 +458,13 @@ export interface DocsAddResult {
   slug?: string;
   /** Type classification recorded for this attachment, when provided (T9637). */
   type?: DocsType;
+  /**
+   * Auto-allocated ADR number, present iff the slug was minted by
+   * {@link allocateAdrSlug} (i.e. `--type adr` without `--slug`).
+   *
+   * @task T10360
+   */
+  adrNumber?: number;
 }
 
 // --------------------------------------------------------------------------
@@ -481,6 +499,157 @@ export interface DocsRemoveResult {
   attachmentBackend?: AttachmentBackend;
 }
 
+// --------------------------------------------------------------------------
+// docs.update — UPDATE-in-place via slug (T10161)
+// --------------------------------------------------------------------------
+
+/**
+ * Allowed `lifecycle_status` values mirrored from the attachments-table enum
+ * (`ATTACHMENT_LIFECYCLE_STATUSES` in
+ * `packages/core/src/store/schema/attachments.ts`). Kept inline here so the
+ * contract surface stays self-contained — the dispatch handler narrows raw
+ * `--status` input against this set before touching the store.
+ *
+ * @task T10161 (Epic T10157 / Saga T9855)
+ */
+export type DocsLifecycleStatus =
+  | 'draft'
+  | 'proposed'
+  | 'accepted'
+  | 'superseded'
+  | 'archived'
+  | 'deprecated';
+
+/**
+ * Parameters for `docs.update`.
+ *
+ * Replaces the blob content for an existing slug — the slug is transferred
+ * from the old `attachments` row to a new row carrying the new sha256, and
+ * the old row remains reachable by attachment-id for history. Unlike
+ * {@link DocsSupersedeParams}-style flows, NO supersession edge is created
+ * (callers wanting an explicit lineage edge should use `cleo docs supersede`).
+ *
+ * Exactly one of `file` or `content` MUST be provided.
+ *
+ * @task T10161 (Epic T10157 / Saga T9855 — E12.C4)
+ */
+export interface DocsUpdateParams {
+  /** Slug of the existing attachment to update (required). */
+  slug: string;
+  /** Path to a local file containing the new content. */
+  file?: string;
+  /** Inline UTF-8 content (mutually exclusive with `file`). */
+  content?: string;
+  /** Optional one-line summary describing the change (recorded in the audit log). */
+  message?: string;
+  /**
+   * Override the new lifecycle status. Defaults to `'draft'` on every update
+   * so an explicit `accepted` doc gets back-pressured to draft on edit. Pass
+   * `--status accepted` (or any other valid status) to override.
+   */
+  status?: DocsLifecycleStatus;
+  /** Agent identity that performed the update (default: `'human'`). */
+  attachedBy?: string;
+}
+
+/**
+ * Result of `docs.update`.
+ *
+ * Identifies the new row (active) and the row it replaced. When the supplied
+ * content is byte-identical to the current content the operation is a noop —
+ * `previousSha256` will equal `sha256` and `changed` will be `false`.
+ *
+ * @task T10161
+ */
+export interface DocsUpdateResult {
+  /** Slug that now points at the new content. */
+  slug: string;
+  /** Type/kind of the row, preserved from the prior version. */
+  type?: DocsType;
+  /** New attachment ID now bearing the slug. */
+  attachmentId: string;
+  /** Previous attachment ID; retains its row + bytes for history. */
+  previousAttachmentId: string;
+  /** SHA-256 hex of the new content. */
+  sha256: string;
+  /** SHA-256 hex of the prior content (equals `sha256` on a noop). */
+  previousSha256: string;
+  /** Whether the bytes actually changed (false ⇒ noop). */
+  changed: boolean;
+  /** Lifecycle status now stored on the new row. */
+  lifecycleStatus: DocsLifecycleStatus;
+  /** ISO 8601 timestamp the new row was registered. */
+  updatedAt: string;
+  /**
+   * Best-effort 1-indexed version number for the slug (count of historical
+   * rows that ever carried this slug, including the current one). When the
+   * underlying store cannot enumerate history this falls back to `2` for the
+   * first update and increments by 1 thereafter.
+   */
+  version: number;
+  /**
+   * True when this update was squashed into an existing audit entry within
+   * the 5-minute squash window (no new audit line was written).
+   */
+  squashed: boolean;
+}
+
+// --------------------------------------------------------------------------
+// docs.supersede — flip an old doc to `superseded` and point at its successor
+// --------------------------------------------------------------------------
+
+/**
+ * Parameters for `docs.supersede`.
+ *
+ * Both `oldSlug` and `newSlug` reference rows on `attachments.slug`. The
+ * operation is atomic: either both rows update (and the lifecycle flip lands)
+ * or neither does.
+ *
+ * @task T10162 (Saga T9855 · Epic T10157 · ADR-078)
+ */
+export interface DocsSupersedeParams {
+  /** Slug of the doc being replaced. */
+  oldSlug: string;
+  /** Slug of the doc that replaces {@link oldSlug}. */
+  newSlug: string;
+  /**
+   * Optional human-readable reason surfaced on the response envelope and
+   * preserved by future provenance-graph reads (T10166 `summary` field on
+   * the `supersedes` edge). Not persisted to a dedicated column today.
+   */
+  reason?: string;
+}
+
+/**
+ * Result of `docs.supersede`.
+ *
+ * @task T10162 (Saga T9855 · Epic T10157 · ADR-078)
+ */
+export interface DocsSupersedeResult {
+  /** Slug of the doc that was just superseded. */
+  oldSlug: string;
+  /** Slug of the new doc that supersedes {@link oldSlug}. */
+  newSlug: string;
+  /** Attachment ID resolved from {@link oldSlug}. */
+  oldAttachmentId: string;
+  /** Attachment ID resolved from {@link newSlug}. */
+  newAttachmentId: string;
+  /** ISO-8601 timestamp the supersession was recorded. */
+  supersededAt: string;
+  /**
+   * Stable identifier for the lineage edge minted by this call.
+   *
+   * The edge itself is not stored in a dedicated table — it is reconstructed
+   * at read time from `attachments.supersedes` / `attachments.superseded_by`
+   * by `cleo docs provenance` (T10166). The ID is deterministic
+   * (`supersedes:<newAttachmentId>->&<oldAttachmentId>`) so concurrent callers
+   * that win the transaction race observe a stable value.
+   */
+  edgeId: string;
+  /** Optional reason carried through from the request. */
+  reason?: string;
+}
+
 // ============================================================================
 // Discriminated Union (DocsOps)
 // ============================================================================
@@ -500,7 +669,9 @@ export type DocsOps =
   | { op: 'docs.fetch'; params: DocsFetchParams; result: DocsFetchResult }
   | { op: 'docs.generate'; params: DocsGenerateParams; result: DocsGenerateResult }
   | { op: 'docs.add'; params: DocsAddParams; result: DocsAddResult }
-  | { op: 'docs.remove'; params: DocsRemoveParams; result: DocsRemoveResult };
+  | { op: 'docs.remove'; params: DocsRemoveParams; result: DocsRemoveResult }
+  | { op: 'docs.update'; params: DocsUpdateParams; result: DocsUpdateResult }
+  | { op: 'docs.supersede'; params: DocsSupersedeParams; result: DocsSupersedeResult };
 
 /**
  * Enumeration of all docs domain operation names.
@@ -509,4 +680,11 @@ export type DocsOps =
  * Useful for dynamic operation dispatch, type narrowing, or documentation.
  * Kept in sync with the `DocsOps` discriminated union above.
  */
-export type DocsOp = 'docs.list' | 'docs.fetch' | 'docs.generate' | 'docs.add' | 'docs.remove';
+export type DocsOp =
+  | 'docs.list'
+  | 'docs.fetch'
+  | 'docs.generate'
+  | 'docs.add'
+  | 'docs.remove'
+  | 'docs.update'
+  | 'docs.supersede';

package/src/operations/tasks.ts

@@ -125,6 +125,45 @@ export interface TasksFindParams {
    * @task T9072
    */
   kind?: string;
+  /**
+   * Unified urgency surface (T9905).
+   *
+   * When `true`, the predicate is
+   *
+   *   `priority IN ('critical','high') OR severity IN ('P0','P1')`
+   *
+   * combining the two orthogonal urgency axes (priority + severity) into a
+   * single filter. Composes with other filters via AND.
+   *
+   * @task T9905
+   */
+  urgent?: boolean;
+  /**
+   * Filter by label — selects tasks whose `labels` array contains this
+   * value. Composes with other filters via AND.
+   *
+   * Closes GH#393 — gives `cleo find --label <name>` parity with the
+   * positional `cleo labels <name>` surface.
+   *
+   * @task T9904
+   */
+  label?: string;
+  /**
+   * Filter by parent task ID — restricts the result set to tasks whose
+   * `parentId` equals this value. Mirrors the `--parent` axis on
+   * `cleo list`. When the parent task is a Saga (Epic with
+   * `label='saga'`), routing goes through `task_relations.type='groups'`
+   * member IDs instead of the `parentId` column (ADR-073 §1).
+   *
+   * Composes with other filters via AND. Closes T10108 — pre-fix,
+   * `cleo find "" --parent <id>` returned every task in the project
+   * because the empty-string query bypassed all filters via
+   * `fuzzyScore('', '<title>')===80`.
+   *
+   * @task T10108
+   * @saga T9862
+   */
+  parent?: string;
 }
 export type TasksFindResult = MinimalTask[];
 

package/src/task-record.ts

@@ -103,4 +103,11 @@ export interface MinimalTaskRecord {
   type?: string;
   /** Scope size estimate — helps agents decide if decomposition is needed. @task T091 */
   size?: string;
+  /**
+   * Bug severity axis — P0|P1|P2|P3 (string-widened). Surfaced so the unified
+   * urgency surface (`cleo find --urgent`) can identify P0/P1 rows without a
+   * follow-up `cleo show` per row.
+   * @task T9905
+   */
+  severity?: string | null;
 }