@cleocode/contracts 2026.8.1 → 2026.8.3

package/dist/caamp-markers.d.ts

@@ -0,0 +1,99 @@
+/**
+ * CAAMP instruction-block marker grammar — the single source of truth.
+ *
+ * CAAMP delimits the region it owns inside an agent instruction file
+ * (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, …) with a pair of HTML comments:
+ *
+ * ```markdown
+ * <!-- CAAMP:START -->
+ * @~/.cleo/templates/CLEO-INJECTION.md
+ * <!-- CAAMP:END -->
+ * ```
+ *
+ * Before T12051 this grammar was re-declared as inline string and regex
+ * literals in at least five places — `caamp/core/instructions/injector.ts`,
+ * `caamp/core/harness/pi.ts`, `core/injection.ts`, `core/bootstrap.ts` and
+ * `core/validation/doctor/checks.ts`. Each copy recognised a slightly
+ * different dialect, so a file that one module considered healthy another
+ * considered corrupt.
+ *
+ * The grammar lives here, in the leaf package, because `@cleocode/core` and
+ * `@cleocode/caamp` depend on each other and therefore cannot import the
+ * grammar from one another without a cycle.
+ *
+ * This module is **const data only** — no runtime helpers — so it satisfies
+ * the contracts-purity gate (`scripts/lint-no-runtime-in-contracts.mjs`).
+ * The engine that consumes these patterns lives in
+ * `packages/caamp/src/core/instructions/markers.ts`.
+ *
+ * @task T12051
+ * @see {@link https://github.com/kryptobaseddev/cleo} ADR-064 (CAAMP↔Adapters boundary)
+ */
+/** Canonical opening marker of a CAAMP-managed block. */
+export declare const CAAMP_MARKER_START = "<!-- CAAMP:START -->";
+/** Canonical closing marker of a CAAMP-managed block. */
+export declare const CAAMP_MARKER_END = "<!-- CAAMP:END -->";
+/**
+ * Source of the strict, canonical block pattern.
+ *
+ * Capture group 1 is the block's inner content. Build a fresh `RegExp` from
+ * this string at every use site — a module-level `RegExp` carrying the `g`
+ * flag keeps a mutable `lastIndex`, which silently skips matches when the
+ * same object is reused across `.test()` / `.exec()` calls.
+ *
+ * @example
+ * ```typescript
+ * const pattern = new RegExp(CAAMP_BLOCK_PATTERN_SOURCE, 'g');
+ * ```
+ */
+export declare const CAAMP_BLOCK_PATTERN_SOURCE = "<!-- CAAMP:START -->([\\s\\S]*?)<!-- CAAMP:END -->";
+/**
+ * Source of the damage-tolerant pattern matching an opening marker line.
+ *
+ * Use with the `gmi` flags. Matches all of:
+ *
+ * | Form                     | Damage                     |
+ * | ------------------------ | -------------------------- |
+ * | `<!-- CAAMP:START -->`   | none (canonical)           |
+ * | `!-- CAAMP:START -->`    | leading `<` lost           |
+ * | `<!-- CAAMP:START --`    | trailing `>` lost          |
+ * | `<!--CAAMP:START-->`     | spaces collapsed           |
+ * | `<!-- caamp:start -->`   | case folded                |
+ *
+ * A bare `CAAMP:START` with no comment punctuation at all is deliberately NOT
+ * matched — see {@link damagedMarkerSource}.
+ *
+ * @example
+ * ```typescript
+ * const damaged = new RegExp(CAAMP_DAMAGED_START_PATTERN_SOURCE, 'gmi');
+ * const healed = content.replace(damaged, CAAMP_MARKER_START);
+ * ```
+ */
+export declare const CAAMP_DAMAGED_START_PATTERN_SOURCE: string;
+/**
+ * Source of the damage-tolerant pattern matching a closing marker line.
+ *
+ * Mirrors {@link CAAMP_DAMAGED_START_PATTERN_SOURCE} for `CAAMP:END`. Use
+ * with the `gmi` flags.
+ */
+export declare const CAAMP_DAMAGED_END_PATTERN_SOURCE: string;
+/**
+ * The outcome of writing a CAAMP block into an instruction file.
+ *
+ * Previously re-declared as an inline union in eight separate locations.
+ *
+ * - `created` — the file did not exist and was written from scratch.
+ * - `added` — the file existed with no CAAMP block; one was prepended.
+ * - `repaired` — at least one damaged marker was healed back to canonical form.
+ * - `consolidated` — several blocks were merged down to exactly one.
+ * - `updated` — a single block existed and its content changed.
+ * - `intact` — the file already had exactly the desired content; no write.
+ */
+export type CaampInjectionAction = 'created' | 'added' | 'repaired' | 'consolidated' | 'updated' | 'intact';
+/**
+ * Every {@link CaampInjectionAction} value, ordered from most to least
+ * invasive. Useful for reporting the single most significant action taken
+ * across a batch of files.
+ */
+export declare const CAAMP_INJECTION_ACTIONS: readonly ["created", "added", "repaired", "consolidated", "updated", "intact"];
+//# sourceMappingURL=caamp-markers.d.ts.map

package/dist/caamp-markers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caamp-markers.d.ts","sourceRoot":"","sources":["../src/caamp-markers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,yDAAyD;AACzD,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD,yDAAyD;AACzD,eAAO,MAAM,gBAAgB,uBAAuB,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,0BAA0B,uDAAuD,CAAC;AAiC/F;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,kCAAkC,QAA+B,CAAC;AAE/E;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,QAA6B,CAAC;AAE3E;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,oBAAoB,GAC5B,SAAS,GACT,OAAO,GACP,UAAU,GACV,cAAc,GACd,SAAS,GACT,QAAQ,CAAC;AAEb;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,gFAO1B,CAAC"}

package/dist/caamp-markers.js

@@ -0,0 +1,121 @@
+/**
+ * CAAMP instruction-block marker grammar — the single source of truth.
+ *
+ * CAAMP delimits the region it owns inside an agent instruction file
+ * (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, …) with a pair of HTML comments:
+ *
+ * ```markdown
+ * <!-- CAAMP:START -->
+ * @~/.cleo/templates/CLEO-INJECTION.md
+ * <!-- CAAMP:END -->
+ * ```
+ *
+ * Before T12051 this grammar was re-declared as inline string and regex
+ * literals in at least five places — `caamp/core/instructions/injector.ts`,
+ * `caamp/core/harness/pi.ts`, `core/injection.ts`, `core/bootstrap.ts` and
+ * `core/validation/doctor/checks.ts`. Each copy recognised a slightly
+ * different dialect, so a file that one module considered healthy another
+ * considered corrupt.
+ *
+ * The grammar lives here, in the leaf package, because `@cleocode/core` and
+ * `@cleocode/caamp` depend on each other and therefore cannot import the
+ * grammar from one another without a cycle.
+ *
+ * This module is **const data only** — no runtime helpers — so it satisfies
+ * the contracts-purity gate (`scripts/lint-no-runtime-in-contracts.mjs`).
+ * The engine that consumes these patterns lives in
+ * `packages/caamp/src/core/instructions/markers.ts`.
+ *
+ * @task T12051
+ * @see {@link https://github.com/kryptobaseddev/cleo} ADR-064 (CAAMP↔Adapters boundary)
+ */
+/** Canonical opening marker of a CAAMP-managed block. */
+export const CAAMP_MARKER_START = '<!-- CAAMP:START -->';
+/** Canonical closing marker of a CAAMP-managed block. */
+export const CAAMP_MARKER_END = '<!-- CAAMP:END -->';
+/**
+ * Source of the strict, canonical block pattern.
+ *
+ * Capture group 1 is the block's inner content. Build a fresh `RegExp` from
+ * this string at every use site — a module-level `RegExp` carrying the `g`
+ * flag keeps a mutable `lastIndex`, which silently skips matches when the
+ * same object is reused across `.test()` / `.exec()` calls.
+ *
+ * @example
+ * ```typescript
+ * const pattern = new RegExp(CAAMP_BLOCK_PATTERN_SOURCE, 'g');
+ * ```
+ */
+export const CAAMP_BLOCK_PATTERN_SOURCE = '<!-- CAAMP:START -->([\\s\\S]*?)<!-- CAAMP:END -->';
+/**
+ * Horizontal-whitespace class used by the damage-tolerant marker patterns.
+ *
+ * Deliberately excludes `\n` so the patterns stay anchored to a single line
+ * and cannot swallow surrounding content.
+ */
+const H = '[ \\t\\r]';
+/**
+ * Build the source of a damage-tolerant, whole-line marker pattern.
+ *
+ * Recognises the canonical marker plus the near-miss forms produced when a
+ * delimiter character is lost or mangled — a truncated write, an editor that
+ * reflows HTML comments, a shell heredoc, a careless hand edit.
+ *
+ * Two constraints keep this from over-matching, both learned from an
+ * adversarial review that demonstrated content loss with a looser pattern:
+ *
+ * 1. The `CAAMP:<KEYWORD>` token must be the *entire* line, modulo comment
+ *    punctuation and horizontal whitespace. Prose such as "the CAAMP:START
+ *    marker is written by …" is therefore never matched.
+ * 2. Comment punctuation must be present on **both** sides — at least one of
+ *    `< ! -` before the token and at least one of `- >` after it. A bare
+ *    `CAAMP:START` line is deliberately NOT treated as a damaged marker: it is
+ *    not a plausible outcome of losing one delimiter character, and accepting
+ *    it caused a documentation fence that merely *mentioned* CAAMP to be
+ *    rewritten into a real marker, silently swallowing the fenced body.
+ */
+const damagedMarkerSource = (keyword) => `^${H}*[<!-]{1,4}${H}*CAAMP${H}*:${H}*${keyword}${H}*[->]{1,3}${H}*$`;
+/**
+ * Source of the damage-tolerant pattern matching an opening marker line.
+ *
+ * Use with the `gmi` flags. Matches all of:
+ *
+ * | Form                     | Damage                     |
+ * | ------------------------ | -------------------------- |
+ * | `<!-- CAAMP:START -->`   | none (canonical)           |
+ * | `!-- CAAMP:START -->`    | leading `<` lost           |
+ * | `<!-- CAAMP:START --`    | trailing `>` lost          |
+ * | `<!--CAAMP:START-->`     | spaces collapsed           |
+ * | `<!-- caamp:start -->`   | case folded                |
+ *
+ * A bare `CAAMP:START` with no comment punctuation at all is deliberately NOT
+ * matched — see {@link damagedMarkerSource}.
+ *
+ * @example
+ * ```typescript
+ * const damaged = new RegExp(CAAMP_DAMAGED_START_PATTERN_SOURCE, 'gmi');
+ * const healed = content.replace(damaged, CAAMP_MARKER_START);
+ * ```
+ */
+export const CAAMP_DAMAGED_START_PATTERN_SOURCE = damagedMarkerSource('START');
+/**
+ * Source of the damage-tolerant pattern matching a closing marker line.
+ *
+ * Mirrors {@link CAAMP_DAMAGED_START_PATTERN_SOURCE} for `CAAMP:END`. Use
+ * with the `gmi` flags.
+ */
+export const CAAMP_DAMAGED_END_PATTERN_SOURCE = damagedMarkerSource('END');
+/**
+ * Every {@link CaampInjectionAction} value, ordered from most to least
+ * invasive. Useful for reporting the single most significant action taken
+ * across a batch of files.
+ */
+export const CAAMP_INJECTION_ACTIONS = [
+    'created',
+    'added',
+    'repaired',
+    'consolidated',
+    'updated',
+    'intact',
+];
+//# sourceMappingURL=caamp-markers.js.map

package/dist/caamp-markers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"caamp-markers.js","sourceRoot":"","sources":["../src/caamp-markers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,yDAAyD;AACzD,MAAM,CAAC,MAAM,kBAAkB,GAAG,sBAAsB,CAAC;AAEzD,yDAAyD;AACzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,oBAAoB,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,oDAAoD,CAAC;AAE/F;;;;;GAKG;AACH,MAAM,CAAC,GAAG,WAAW,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,mBAAmB,GAAG,CAAC,OAAwB,EAAU,EAAE,CAC/D,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,OAAO,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAE/E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;AAsB3E;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,SAAS;IACT,OAAO;IACP,UAAU;IACV,cAAc;IACd,SAAS;IACT,QAAQ;CACA,CAAC"}

package/dist/changesets.d.ts

@@ -82,8 +82,8 @@ export declare const ChangesetReleaseNotesMetadataSchema: z.ZodObject<{
         deprecated: "deprecated";
         security: "security";
         fixed: "fixed";
-        breaking: "breaking";
         added: "added";
+        breaking: "breaking";
         changed: "changed";
     }>>;
     audience: z.ZodOptional<z.ZodArray<z.ZodEnum<{
@@ -149,8 +149,8 @@ export declare const ChangesetEntrySchema: z.ZodObject<{
             deprecated: "deprecated";
             security: "security";
             fixed: "fixed";
-            breaking: "breaking";
             added: "added";
+            breaking: "breaking";
             changed: "changed";
         }>>;
         audience: z.ZodOptional<z.ZodArray<z.ZodEnum<{

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)