@cleocode/contracts 2026.8.9 → 2026.9.2

package/src/acceptance-gate.ts

@@ -335,7 +335,24 @@ export interface AcceptanceGateResult {
   req?: string;
   /** Gate variant. */
   kind: AcceptanceGateKind;
-  /** Outcome of the gate execution. */
+  /**
+   * Outcome of the gate execution.
+   *
+   * `fail` and `error` are NOT interchangeable, and the difference is the whole
+   * point of having both (gh#1270):
+   *
+   * - `pass` — ran to completion, satisfied.
+   * - `fail` — ran to completion, **found a problem**. A verdict.
+   * - `warn` — a `fail` on a gate marked `advisory`.
+   * - `skipped` — deliberately not run.
+   * - `error` — **did not finish**: killed by timeout or signal, or could not
+   *   be executed. This is *not a verdict*. Recording it as `fail` produces a
+   *   false red, which costs an agent work it had actually completed and writes
+   *   an assertion into the evidence record that a check found a problem when
+   *   none was ever made. Consumers must treat `error` as "unknown, re-run",
+   *   never as "failed" — see the mapping in `lifecycle/index.ts`, which
+   *   resolves it to `pending`.
+   */
   result: 'pass' | 'fail' | 'warn' | 'skipped' | 'error';
   /** Wall-clock duration of the gate execution in milliseconds. */
   durationMs: number;

package/src/branch-lock.ts

@@ -89,6 +89,30 @@ export interface WorktreeMergeResult {
   branchDeleted: boolean;
   /** Error message if any step failed (non-fatal — caller decides). */
   error?: string;
+  /**
+   * True when there was **nothing to integrate** — no `task/<taskId>` branch and
+   * no worktree directory ever existed for this task.
+   *
+   * @remarks
+   * T12153 (GH #1223): this is NOT a failure, and conflating it with one made
+   * `cleo complete` log
+   *
+   * ```
+   * WARN … mergeError: "task branch 'task/T1655' does not exist"
+   * ```
+   *
+   * for every task worked on a feature branch and merged by PR — which is most
+   * of them. `merged: false` plus an `error` was the only shape available, so a
+   * routine, correct outcome was reported at WARN as an integration failure.
+   *
+   * Noise at WARN is worse than silence: it trains a reader to ignore a channel
+   * that should mean something, so the one genuine rebase conflict is filtered
+   * out along with the hundred non-events.
+   *
+   * Callers should treat `nothingToIntegrate: true` as success-with-no-work,
+   * and reserve failure handling for `merged: false` WITHOUT this flag.
+   */
+  nothingToIntegrate?: boolean;
 }
 
 /**

package/src/conduit.ts

@@ -119,12 +119,45 @@ export interface ConduitSendOptions {
   metadata?: Record<string, unknown>;
 }
 
-/** Result of sending a message. */
+/**
+ * Result of sending a message.
+ *
+ * ## Why `deliveredAt` is nullable (gh#1316)
+ *
+ * It was `deliveredAt: string`, and `ConduitClient.send` filled it with
+ * `new Date().toISOString()` for a row the transport had just written with
+ * `status = 'pending'`. That is not an approximation of a delivery time — the
+ * transport returns none, the row says the message is undelivered, and the
+ * schema has a SEPARATE real `delivered_at` that a different code path fills in
+ * later. The system models the distinction correctly everywhere except at the
+ * boundary where it is reported.
+ *
+ * Because the field was REQUIRED, "accepted but not yet delivered" — the normal
+ * case, and the state every message passes through — was **unrepresentable at
+ * the type level**. So the only way to satisfy the contract was to invent a
+ * value, which is what the code did.
+ *
+ * The two facts are now separate: `acceptedAt` is what a send genuinely knows,
+ * and `deliveredAt` is `null` until delivery actually happens.
+ */
 export interface ConduitSendResult {
   /** The assigned message ID. */
   messageId: string;
-  /** ISO 8601 timestamp of delivery. */
-  deliveredAt: string;
+  /**
+   * ISO 8601 timestamp at which the transport ACCEPTED the message.
+   *
+   * Always known at send time. This is what the old `deliveredAt` actually
+   * contained.
+   */
+  acceptedAt: string;
+  /**
+   * ISO 8601 timestamp of actual delivery, or `null` when not yet delivered.
+   *
+   * `null` is the normal result of a `send`: the row is written `pending` and a
+   * later path records real delivery. A non-null value here means delivery is
+   * confirmed — never that it is assumed.
+   */
+  deliveredAt: string | null;
 }
 
 /** Unsubscribe function returned by event subscriptions. */

package/src/data-accessor.ts

@@ -15,7 +15,15 @@
 
 import type { ArchivedTask } from './archive.js';
 import type { Session } from './session.js';
-import type { Task, TaskPriority, TaskSize, TaskStatus, TaskType } from './task.js';
+import type {
+  Task,
+  TaskKind,
+  TaskPriority,
+  TaskSeverity,
+  TaskSize,
+  TaskStatus,
+  TaskType,
+} from './task.js';
 
 /**
  * Agent instance row shape for DataAccessor methods.
@@ -59,6 +67,27 @@ export interface TaskQueryFilters {
   status?: TaskStatus | TaskStatus[];
   priority?: TaskPriority;
   type?: TaskType;
+  /**
+   * Severity axis filter (`P0`-`P3`). Orthogonal to {@link priority}.
+   *
+   * @remarks
+   * T12120 (GH #1245): `severity` is a first-class ADR-066 axis that
+   * `cleo add --severity` persists, but it had no read path at any layer —
+   * so `cleo list --severity P0` returned every task with no signal that the
+   * constraint had been dropped. A filter that is accepted and not applied
+   * fails OPEN, which is the most dangerous possible answer to "show me only
+   * the critical items".
+   */
+  severity?: TaskSeverity | TaskSeverity[];
+  /**
+   * Kind axis filter (`work`/`research`/`experiment`/`bug`/`spike`/`release`).
+   * Orthogonal to {@link type}. Stored in the `role` DB column.
+   *
+   * @remarks
+   * T12120 (GH #1245): missing from the read path for the same reason as
+   * {@link severity}.
+   */
+  kind?: TaskKind | TaskKind[];
   parentId?: string | null; // null = root tasks only
   phase?: string;
   label?: string;

package/src/dispatch/operations-registry.ts

@@ -292,19 +292,34 @@ export const OPERATIONS: OperationDef[] = [
       { name: 'status', type: 'string', required: false, description: 'Filter by task status' },
       { name: 'priority', type: 'string', required: false, description: 'Filter by task priority' },
       { name: 'type', type: 'string', required: false, description: 'Filter by task type' },
+      {
+        name: 'severity',
+        type: 'string',
+        required: false,
+        description: 'Filter by severity axis (P0|P1|P2|P3); invalid values are rejected',
+      },
+      {
+        name: 'kind',
+        type: 'string',
+        required: false,
+        description:
+          'Filter by kind axis (work|research|experiment|bug|spike|release); invalid values are rejected',
+      },
       { name: 'phase', type: 'string', required: false, description: 'Filter by task phase' },
       { name: 'label', type: 'string', required: false, description: 'Filter by task label' },
       {
         name: 'children',
         type: 'boolean',
         required: false,
-        description: 'Limit parent queries to direct children',
+        description:
+          'DEPRECATED (no effect; slated for removal in a future major): --parent already returns DIRECT children only, for every parent type including sagas. Do not use.',
       },
       {
         name: 'limit',
         type: 'number',
         required: false,
-        description: 'Maximum number of tasks to return',
+        description:
+          'Maximum number of tasks to return (default 10). Use --all to return every match. (--limit 0 also returns every match, but only on this command — prefer --all.)',
       },
       {
         name: 'offset',

package/src/index.ts

@@ -2669,3 +2669,5 @@ export {
 } from './caamp-markers.js';
 // T12077: SSoT for the keys under which payloads carry their rows.
 export { COLLECTION_KEYS, type CollectionKey } from './collection-keys.js';
+
+export { isStorableTaskId, isTaskId, TASK_ID_REGEX, type TaskId } from './task-id.js';

package/src/operations/output-contracts-data.ts

@@ -66,10 +66,15 @@ const tasksShowOutputContract: OperationOutputContract = {
   operation: 'tasks.show',
   shapeNote:
     'The task record is nested under `task` — use /data/task/<field>, not /data/<field>. ' +
+    'Mutation envelopes are FLAT by contrast (/data/created/0, /data/updated/0), which is ' +
+    'the asymmetry that produced GH #1225/#1239/#1231. ' +
     '`view` may be null. `acRows` and `relations` are conditional. ' +
-    'The listed pointers are the default (MVI) projection — `verification`, `acceptance`, ' +
-    '`description`, and `evidence` live only in the full record (`cleo show <id> --full`); ' +
-    '`--field` resolves them transparently when they exist (T12108).',
+    '`description`, `acceptance` and `verification` are withheld by the default (MVI) ' +
+    'projection but `--field` resolves them transparently (T12108) — no `--full` needed. ' +
+    'Evidence is NOT a task field: it lives at /data/task/verification/evidence ' +
+    '(keyed by gate), alongside /data/task/verification/gates. T12127 (GH #1231) — the ' +
+    'previous wording advertised `/data/task/evidence`, which does not exist, in the very ' +
+    'text shown to an agent whose pointer had just failed.',
   dataSchema: {
     type: 'object',
     required: ['task', 'view', 'attachments'],
@@ -114,6 +119,16 @@ const tasksShowOutputContract: OperationOutputContract = {
     '/data/task/priority',
     '/data/task/type',
     '/data/task/parentId',
+    // T12127 (GH #1231) — withheld by the MVI projection but resolvable
+    // through `--field` since T12108. They were absent from this list, so the
+    // remediation an agent is shown on a failed pointer never mentioned the
+    // fields it most often wanted, and `cleo show --field /data/task` came
+    // back looking like a write that had silently done nothing.
+    '/data/task/description',
+    '/data/task/acceptance',
+    '/data/task/verification',
+    '/data/task/verification/gates',
+    '/data/task/verification/evidence',
     '/data/view/id',
     '/data/view/title',
   ],

package/src/operations/session.ts

@@ -242,6 +242,17 @@ export interface BriefingFieldRule {
    * Violations are emitted when an item carries one of these provenance values.
    */
   excludeProvenance?: BriefingExcludeProvenance[];
+  /**
+   * Keys that MUST be present on this field's object, even when the value is
+   * `null`. Applies to object-valued fields (not lists) and exists to stop an
+   * absent key from being indistinguishable from a recorded-empty one.
+   *
+   * The motivating case (GH #1277) is `lastSession.handoff.note`: a handoff
+   * that recorded no note omitted the key entirely, so a lost handoff and a
+   * note-free handoff were byte-identical to a consumer. `null` satisfies the
+   * rule; a missing key does not.
+   */
+  requireKeys?: readonly string[];
 }
 
 /**
@@ -284,8 +295,9 @@ export interface ContractViolation {
    * - `stale` — field data exceeds `maxAgeDays`.
    * - `duplicate` — two items share the same `dedupBy` key value.
    * - `excluded-provenance` — item carries a banned provenance tag.
+   * - `missing-key` — an object field omits a key named in `requireKeys`.
    */
-  kind: 'stale' | 'duplicate' | 'excluded-provenance';
+  kind: 'stale' | 'duplicate' | 'excluded-provenance' | 'missing-key';
   /** Severity — P0 violations block `cleo briefing --strict`. */
   severity: 'P0' | 'P1';
 }

package/src/operations/tasks.ts

@@ -24,7 +24,7 @@ import type { TaskAnalysisResult, TaskRef } from '../results.js';
  * Common task types (API contract — matches CLI src/types/task.ts)
  */
 import type { TaskStatus } from '../status-registry.js';
-import type { TaskPriority, TaskType } from '../task.js';
+import type { TaskKind, TaskPriority, TaskSeverity, TaskType } from '../task.js';
 import type { TaskRecord } from '../task-record.js';
 import type { ExternalTask, ExternalTaskLink, ReconcileResult } from '../task-sync.js';
 import type {
@@ -83,8 +83,34 @@ export interface TasksListParams {
   status?: TaskStatus;
   priority?: TaskPriority;
   type?: string;
+  /**
+   * Filter by severity axis (`P0`-`P3`), orthogonal to {@link priority}.
+   *
+   * @remarks
+   * T12120 (GH #1245): previously absent from every layer of the read path,
+   * so `cleo list --severity P0` returned every task with no signal that the
+   * constraint had been dropped. Values outside `TASK_SEVERITIES` are rejected
+   * with `E_VALIDATION` — an unrecognised filter value must never widen a
+   * result set.
+   */
+  severity?: TaskSeverity | TaskSeverity[];
+  /**
+   * Filter by kind axis (ADR-066), orthogonal to {@link type}.
+   *
+   * @remarks
+   * T12120 (GH #1246): absent from the read path for the same reason as
+   * {@link severity}. Stored in the `role` DB column.
+   */
+  kind?: TaskKind | TaskKind[];
   phase?: string;
   label?: string;
+  /**
+   * No-op, retained for compatibility.
+   *
+   * @remarks
+   * T12120 (GH #1247): `--parent` already restricts to DIRECT children on
+   * every path, so there is no transitive mode for this flag to narrow from.
+   */
   children?: boolean;
   limit?: number;
   offset?: number;
@@ -1401,6 +1427,18 @@ export interface TasksAddParams {
   description?: string;
   /** Canonical wire field for parent task ID. @see ADR-057 D2 */
   parent?: string;
+  /**
+   * Where {@link parent} came from, when the caller knows.
+   *
+   * @remarks
+   * T12136 (GH #1232/#1238): the CLI infers a parent from the session's
+   * `current` pointer before dispatch, so core cannot tell an inherited parent
+   * from a named one. Without that distinction
+   * `E_CLEO_DEPTH_EXCEEDED` names a task the caller never mentioned and
+   * suggests reparenting into a hierarchy it never intended to touch.
+   * Defaults to `'explicit'`.
+   */
+  parentSource?: 'explicit' | 'session-inference';
   depends?: string[];
   priority?: string;
   labels?: string[];

package/src/task-id.ts

@@ -0,0 +1,127 @@
+/**
+ * The canonical shape of a task identifier (T12128).
+ *
+ * ## Why this file exists
+ *
+ * The repo carried at least five different opinions about what a task ID looks
+ * like, and they disagreed with each other:
+ *
+ * | pattern | where | disagrees about |
+ * |---|---|---|
+ * | `/^T[0-9]{1,7}$/` | `goal.ts`, `evidence-atom-schema.ts` (8 sites) | upper bound |
+ * | `/^T(\d{3,})$/` | `tasks/id-generator.ts` | rejects `T12`, allows `T123456789` |
+ * | `/^T\d{3,}$/` | `sentient/tick.ts`, `nexus/query.ts` | same |
+ * | `/\bT(\d{4,})\b/` | `lifecycle/consolidate-rcasd.ts` | unanchored, 4-digit minimum |
+ * | `/^(T\d+(-[A-Z]\w*)?\|E-\d+...)$/` | `changesets.ts` | allows suffixes and `E-` |
+ *
+ * Disagreement between validators is survivable. What was not survivable is
+ * that **none of them ran on the write path**. A project path was written into
+ * the `id` column of `tasks_tasks` — `id='/mnt/projects/cleocode'`,
+ * `title='Task /mnt/projects/cleocode'`, `type=null` — and the row is now
+ * **immortal**: `cleo list` returns it, but `cleo show`, `cleo update` and
+ * `cleo delete` all reject the id as malformed before they can reach it. The
+ * read-side validators that would have prevented it are the ones that make it
+ * unfixable.
+ *
+ * {@link TASK_ID_REGEX} deliberately adopts the `{1,7}` shape already used at
+ * eight sites rather than inventing a sixth opinion. It is permissive by
+ * design: the job here is to reject values that are not task IDs at all, not to
+ * re-litigate how many digits a task ID should have. Narrowing it later is a
+ * separate decision with its own migration.
+ *
+ * @module
+ * @task T12128
+ */
+
+/**
+ * Canonical task-identifier pattern: `T` followed by 1-7 digits.
+ *
+ * Anchored at both ends — an unanchored variant would accept `see T1234 for
+ * details` as an id, which is how prose ends up in an id column.
+ */
+export const TASK_ID_REGEX = /^T[0-9]{1,7}$/;
+
+/**
+ * A string known to be a well-formed task identifier.
+ *
+ * Branded so a validated id cannot be confused with an arbitrary string at a
+ * call site that matters.
+ */
+export type TaskId = string & { readonly __brand: 'TaskId' };
+
+/**
+ * Whether `value` is a well-formed task identifier.
+ *
+ * @param value - candidate identifier.
+ * @returns `true` when `value` matches {@link TASK_ID_REGEX}.
+ *
+ * @example
+ * ```ts
+ * isTaskId('T12128');               // true
+ * isTaskId('/mnt/projects/cleo');   // false — the value that got written
+ * isTaskId('see T1234 for details');// false — anchoring matters
+ * ```
+ */
+export function isTaskId(value: unknown): value is TaskId {
+  return typeof value === 'string' && TASK_ID_REGEX.test(value);
+}
+
+/**
+ * Characters and shapes that can never be a task identifier.
+ *
+ * ## Why this exists alongside {@link TASK_ID_REGEX}
+ *
+ * `TASK_ID_REGEX` describes the *canonical* id the generator produces. It is
+ * NOT what the store actually contains, and enforcing it at the write path
+ * would break working features. Measured against a live store of 3,198 tasks:
+ *
+ * | id | origin |
+ * |---|---|
+ * | `T-RECONCILE-FOLLOWUP-v2026.5.63-6` | generated ON PURPOSE by `archive-reason-invariant.ts` |
+ * | `T932EP` | unknown, pre-existing |
+ * | `/mnt/projects/cleocode` | the corruption this guard exists to stop |
+ *
+ * So CLEO deliberately mints structured ids that its own canonical pattern
+ * rejects — and, separately, that `cleo show` rejects too, which makes those
+ * release follow-up tasks as unreachable as the corrupt row. That is a real
+ * defect, but it is a **design** question about the id space, and settling it
+ * inside a guard that stops path-shaped garbage would be scope creep with a
+ * broken `cleo release reconcile` as the cost.
+ *
+ * This predicate therefore rejects only what cannot be an identifier under any
+ * shape: empty, whitespace, path separators, control characters, or absurd
+ * length. It catches the actual harm without taking a position on digits.
+ */
+const FORBIDDEN_IN_TASK_ID = /[\s/\\\x00-\x1f\x7f]/;
+
+/** Longest plausible identifier; anything beyond this is not an id. */
+const MAX_TASK_ID_LENGTH = 64;
+
+/**
+ * Whether `value` is storable as a task identifier.
+ *
+ * Deliberately broader than {@link isTaskId}: it admits every id shape CLEO
+ * actually mints (including the structured `T-RECONCILE-FOLLOWUP-…` ids the
+ * release reconciler creates) while rejecting values that are not identifiers
+ * at all. Use this at write chokepoints; use {@link isTaskId} when you
+ * genuinely need the canonical generated shape.
+ *
+ * @param value - candidate identifier.
+ * @returns `true` when `value` can be stored as an id.
+ *
+ * @example
+ * ```ts
+ * isStorableTaskId('T12128');                          // true
+ * isStorableTaskId('T-RECONCILE-FOLLOWUP-v2026.5.63-6'); // true — CLEO mints these
+ * isStorableTaskId('/mnt/projects/cleocode');          // false — a path
+ * isStorableTaskId('see T1234 for details');           // false — whitespace
+ * ```
+ */
+export function isStorableTaskId(value: unknown): value is TaskId {
+  if (typeof value !== 'string') return false;
+  if (value.length === 0 || value.length > MAX_TASK_ID_LENGTH) return false;
+  if (FORBIDDEN_IN_TASK_ID.test(value)) return false;
+  // An identifier must start with a letter — this rejects paths beginning
+  // `./`, `~`, or a digit-only value that is really a count.
+  return /^[A-Za-z]/.test(value);
+}