@cleocode/contracts 2026.5.114 → 2026.5.120

package/src/__tests__/meta-tokens.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Type-shape contract test for the envelope-wide `meta.tokens` field
+ * promoted in T9923 (Saga T9855 / E8.4).
+ *
+ * `CliMeta.tokens` is the first-class structured token-cost annotation
+ * attached to every CLI envelope (formerly the underscore-prefixed
+ * `meta._tokenEstimate`). The legacy field is retained for ONE release
+ * (removeAt v2026.7.0) so existing consumers can migrate without a
+ * flag-day.
+ *
+ * @epic T9919
+ * @task T9923
+ * @saga T9855
+ */
+
+import type { CliEnvelope, CliMeta, CliMetaTokens } from '@cleocode/lafs';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+describe('CliMeta.tokens type shape (T9923)', () => {
+  it('accepts the full first-class CliMetaTokens shape', () => {
+    const meta: CliMeta = {
+      operation: 'tasks.show',
+      requestId: '00000000-0000-0000-0000-000000000000',
+      duration_ms: 0,
+      timestamp: '2026-05-24T00:00:00.000Z',
+      tokens: {
+        estimate: 1234,
+        model: 'cl100k',
+        calculatedAt: '2026-05-24T00:00:00.000Z',
+      },
+    };
+    expect(meta.tokens?.estimate).toBe(1234);
+    expect(meta.tokens?.model).toBe('cl100k');
+    expect(meta.tokens?.calculatedAt).toBe('2026-05-24T00:00:00.000Z');
+  });
+
+  it('requires `estimate` to be a number when `tokens` is present', () => {
+    expectTypeOf<NonNullable<CliMeta['tokens']>['estimate']>().toEqualTypeOf<number>();
+    expectTypeOf<NonNullable<CliMeta['tokens']>['model']>().toEqualTypeOf<string>();
+    expectTypeOf<NonNullable<CliMeta['tokens']>['calculatedAt']>().toEqualTypeOf<string>();
+  });
+
+  it('is optional — omitting `tokens` leaves a valid CliMeta', () => {
+    const meta: CliMeta = {
+      operation: 'tasks.list',
+      requestId: '00000000-0000-0000-0000-000000000001',
+      duration_ms: 0,
+      timestamp: '2026-05-24T00:00:00.000Z',
+    };
+    expect(meta.tokens).toBeUndefined();
+  });
+
+  it('accepts the legacy `_tokenEstimate` field during the deprecation window', () => {
+    const meta: CliMeta = {
+      operation: 'tasks.show',
+      requestId: '00000000-0000-0000-0000-000000000002',
+      duration_ms: 0,
+      timestamp: '2026-05-24T00:00:00.000Z',
+      _tokenEstimate: { estimate: 999 },
+    };
+    expect(meta._tokenEstimate?.estimate).toBe(999);
+  });
+
+  it('allows BOTH `tokens` and `_tokenEstimate` for backwards-compat dual-write', () => {
+    const meta: CliMeta = {
+      operation: 'tasks.show',
+      requestId: '00000000-0000-0000-0000-000000000003',
+      duration_ms: 0,
+      timestamp: '2026-05-24T00:00:00.000Z',
+      tokens: {
+        estimate: 4321,
+        model: 'o200k',
+        calculatedAt: '2026-05-24T00:00:00.000Z',
+      },
+      _tokenEstimate: { estimate: 4321 },
+    };
+    expect(meta.tokens?.estimate).toBe(meta._tokenEstimate?.estimate);
+  });
+
+  it('flows through CliEnvelope<T>.meta verbatim', () => {
+    const envelope: CliEnvelope<{ taskId: string }> = {
+      success: true,
+      data: { taskId: 'T9923' },
+      meta: {
+        operation: 'tasks.show',
+        requestId: '00000000-0000-0000-0000-000000000004',
+        duration_ms: 1,
+        timestamp: '2026-05-24T00:00:00.000Z',
+        tokens: {
+          estimate: 512,
+          model: 'cl100k',
+          calculatedAt: '2026-05-24T00:00:00.000Z',
+        },
+      },
+    };
+    expect(envelope.meta.tokens?.estimate).toBe(512);
+  });
+
+  it('CliMetaTokens is structurally compatible with manual construction', () => {
+    const t: CliMetaTokens = {
+      estimate: 100,
+      model: 'approx',
+      calculatedAt: '2026-05-24T00:00:00.000Z',
+    };
+    expect(t.estimate).toBe(100);
+  });
+});

package/src/boundary.ts

@@ -492,7 +492,7 @@ export const BOUNDARY_REGISTRY: readonly BoundaryEntry[] = [
       panic_unwind: 'allowed-with-recovery',
       root_escape: 'forbidden',
     },
-    amendments: ['adr-077-worktreeinclude'],
+    amendments: ['adr-087-worktree-ffi-topology'],
     rationale:
       'napi binding shim (515 LOC) for worktrunk-core, used by packages/core spawn-pipeline tests, packages/core/src/scaffold/ensure-config.ts, and shipped via packages/worktree-napi-* per-platform npm packages. Internal-only.',
   },
@@ -510,7 +510,7 @@ export const BOUNDARY_REGISTRY: readonly BoundaryEntry[] = [
       panic_unwind: 'forbidden',
       root_escape: 'forbidden',
     },
-    amendments: ['adr-077-worktreeinclude', 'adr-078-boundary-registry'],
+    amendments: ['adr-077-worktreeinclude-canonical-location', 'adr-078-boundary-registry'],
     rationale:
       'Refactored SoC per ADR-078 amendment 2026-05-23. Worktree primitives core (1,352 LOC) vendored from /mnt/projects/worktrunk per D010, consumed by worktree-napi. Reference implementation of the boundary-registry pattern. Full SDK surface documented in crates/worktrunk-core/README.md (T10223). Internal-only today; publish=true is a future option if external worktree-tooling emerges.',
   },
@@ -868,7 +868,7 @@ export const BOUNDARY_REGISTRY: readonly BoundaryEntry[] = [
       root_escape: 'forbidden',
       fs_writes_outside_root: 'audited',
     },
-    amendments: ['adr-077-worktreeinclude', 'adr-078-boundary-registry'],
+    amendments: ['adr-087-worktree-ffi-topology', 'adr-078-boundary-registry'],
     rationale:
       'Worktree SSoT primitive layer (1,972 LOC) — canonical create/destroy/list/prune/include/copy-on-write bound by @cleocode/paths. Post-PR-#487 the responsibilities are distinct from packages/core/src/worktree/ (SDK-level enrichment). Consumes worktrunk-core via worktree-napi.',
   },

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',

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,19 @@ 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;
 }
 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;
 }