@cleocode/contracts 2026.8.2 → 2026.8.4

package/dist/collection-keys.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The keys under which CLEO payloads carry a list of records.
+ *
+ * ## Why this is a shared constant (T12077)
+ *
+ * Different operations name their collection differently — `tasks.list` emits
+ * `tasks`, the SDK's generic list emits `items`, `tasks.find` emits `results`,
+ * and `tasks.next` emits `suggestions`. Each consumer that wants "the rows"
+ * has historically inlined its own guess, and each wrong guess fails SILENTLY,
+ * because an absent key is indistinguishable from an empty result set.
+ *
+ * Three separate outages traced to exactly this:
+ *
+ * 1. **T12067** — `output-mode.ts` knew only `tasks`/`items`, in three
+ *    separately-inlined lists. `cleo find … --output count` reported 1626
+ *    while `--output id` reported `No ids.` against the same payload.
+ * 2. **T12077 (this)** — `cleo next --output id` / `--output count` reported
+ *    nothing and zero while the envelope held 836 candidates, because
+ *    `suggestions` was in nobody's list.
+ * 3. **T12077 (the severe one)** — `defaultPickTask` in the sentient loop read
+ *    `response.data.tasks` from `cleo.tasks.find()`, which returns
+ *    `{results, total}` *unwrapped*. The key was wrong AND the `data` envelope
+ *    it was reaching through does not exist on the SDK surface, so
+ *    `allCandidates` was **always `[]`**. The autonomous loop therefore
+ *    returned `no-task` on every tick it had ever run — 24 ticks, 0 tasks
+ *    picked, across three months — and looked exactly like "there is no work
+ *    to do" rather than like a bug.
+ *
+ * The lesson those three share is that this list must exist in ONE place that
+ * both the render layer and the SDK consumers import. Adding an operation with
+ * a new collection key now means adding it here, once.
+ *
+ * @task T12077
+ */
+/**
+ * Collection keys in resolution order.
+ *
+ * Order matters only when a payload carries more than one (it should not);
+ * earlier keys win, which keeps the canonical `tasks` shape authoritative.
+ */
+export declare const COLLECTION_KEYS: readonly ["tasks", "items", "results", "suggestions"];
+/** A key under which a payload may carry its rows. */
+export type CollectionKey = (typeof COLLECTION_KEYS)[number];
+//# sourceMappingURL=collection-keys.d.ts.map

package/dist/collection-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-keys.d.ts","sourceRoot":"","sources":["../src/collection-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,uDAAwD,CAAC;AAErF,sDAAsD;AACtD,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/collection-keys.js

@@ -0,0 +1,42 @@
+/**
+ * The keys under which CLEO payloads carry a list of records.
+ *
+ * ## Why this is a shared constant (T12077)
+ *
+ * Different operations name their collection differently — `tasks.list` emits
+ * `tasks`, the SDK's generic list emits `items`, `tasks.find` emits `results`,
+ * and `tasks.next` emits `suggestions`. Each consumer that wants "the rows"
+ * has historically inlined its own guess, and each wrong guess fails SILENTLY,
+ * because an absent key is indistinguishable from an empty result set.
+ *
+ * Three separate outages traced to exactly this:
+ *
+ * 1. **T12067** — `output-mode.ts` knew only `tasks`/`items`, in three
+ *    separately-inlined lists. `cleo find … --output count` reported 1626
+ *    while `--output id` reported `No ids.` against the same payload.
+ * 2. **T12077 (this)** — `cleo next --output id` / `--output count` reported
+ *    nothing and zero while the envelope held 836 candidates, because
+ *    `suggestions` was in nobody's list.
+ * 3. **T12077 (the severe one)** — `defaultPickTask` in the sentient loop read
+ *    `response.data.tasks` from `cleo.tasks.find()`, which returns
+ *    `{results, total}` *unwrapped*. The key was wrong AND the `data` envelope
+ *    it was reaching through does not exist on the SDK surface, so
+ *    `allCandidates` was **always `[]`**. The autonomous loop therefore
+ *    returned `no-task` on every tick it had ever run — 24 ticks, 0 tasks
+ *    picked, across three months — and looked exactly like "there is no work
+ *    to do" rather than like a bug.
+ *
+ * The lesson those three share is that this list must exist in ONE place that
+ * both the render layer and the SDK consumers import. Adding an operation with
+ * a new collection key now means adding it here, once.
+ *
+ * @task T12077
+ */
+/**
+ * Collection keys in resolution order.
+ *
+ * Order matters only when a payload carries more than one (it should not);
+ * earlier keys win, which keeps the canonical `tasks` shape authoritative.
+ */
+export const COLLECTION_KEYS = ['tasks', 'items', 'results', 'suggestions'];
+//# sourceMappingURL=collection-keys.js.map

package/dist/collection-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-keys.js","sourceRoot":"","sources":["../src/collection-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,aAAa,CAAU,CAAC"}

package/dist/dispatch/operations-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operations-registry.d.ts","sourceRoot":"","sources":["../../src/dispatch/operations-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAEjG,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAMvE;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,CAExD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAE1F;AAMD,6DAA6D;AAC7D,eAAO,MAAM,UAAU,EAAE,YAAY,EAyoTpC,CAAC"}
+{"version":3,"file":"operations-registry.d.ts","sourceRoot":"","sources":["../../src/dispatch/operations-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAEjG,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAMvE;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,CAExD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAE1F;AAMD,6DAA6D;AAC7D,eAAO,MAAM,UAAU,EAAE,YAAY,EA+pTpC,CAAC"}

package/dist/dispatch/operations-registry.js

@@ -8120,6 +8120,27 @@ export const OPERATIONS = [
                 required: false,
                 description: 'Commit plan file before dispatching',
             },
+            // T12089: the plan SCOPE. The workflow regenerates the plan when no
+            // committed plan is supplied, and `cleo release plan` requires
+            // `--saga | --epic | --tasks` — so without one of these the dispatched
+            // run dies at "Prepare bump-PR" after a fully green preflight.
+            //
+            // A param absent from this registry is STRIPPED before the domain handler
+            // sees it, silently. `--tasks` was accepted by the CLI, forwarded by the
+            // handler and by `releaseOpen`, and still arrived empty at the workflow
+            // because this declaration was the fourth hop in the chain.
+            {
+                name: 'epic',
+                type: 'string',
+                required: false,
+                description: 'Epic task ID forwarded as the plan scope (e.g. T9999)',
+            },
+            {
+                name: 'tasks',
+                type: 'string',
+                required: false,
+                description: 'Comma-separated task IDs forwarded as the plan scope for a task-scoped release',
+            },
         ],
     },
     // release mutate: reconcile (T9526 / SPEC-T9345 §4.4 — v2 reconcile verb)