@cleocode/contracts 2026.8.1 → 2026.8.3

package/src/caamp-markers.ts

@@ -0,0 +1,149 @@
+/**
+ * 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: 'START' | 'END'): string =>
+  `^${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');
+
+/**
+ * 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 const CAAMP_INJECTION_ACTIONS = [
+  'created',
+  'added',
+  'repaired',
+  'consolidated',
+  'updated',
+  'intact',
+] as const;

package/src/collection-keys.ts

@@ -0,0 +1,45 @@
+/**
+ * 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'] as const;
+
+/** A key under which a payload may carry its rows. */
+export type CollectionKey = (typeof COLLECTION_KEYS)[number];

package/src/dispatch/operations-registry.ts

@@ -8392,6 +8392,28 @@ export const OPERATIONS: OperationDef[] = [
         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',
+      },
     ] satisfies ParamDef[],
   },
 

package/src/index.ts

@@ -2653,4 +2653,18 @@ export {
   workGraphSliceParamsSchema,
   workGraphSliceSchema,
 } from './workgraph.js';
+
 // === WASM SDK (Rust crate bindings) ===
+
+export type { CaampInjectionAction } from './caamp-markers.js';
+// === CAAMP instruction-block marker grammar (T12051) ===
+export {
+  CAAMP_BLOCK_PATTERN_SOURCE,
+  CAAMP_DAMAGED_END_PATTERN_SOURCE,
+  CAAMP_DAMAGED_START_PATTERN_SOURCE,
+  CAAMP_INJECTION_ACTIONS,
+  CAAMP_MARKER_END,
+  CAAMP_MARKER_START,
+} from './caamp-markers.js';
+// T12077: SSoT for the keys under which payloads carry their rows.
+export { COLLECTION_KEYS, type CollectionKey } from './collection-keys.js';

package/src/llm/system-resolver.ts

@@ -124,6 +124,16 @@ export interface ResolveLLMForSystemOptions {
    * without changing the system identity.
    */
   roleOverride?: RoleName;
+  /**
+   * Providers to skip for this resolution (T12084).
+   *
+   * Mirrors `ResolveLLMForRoleOptions.excludeProviders` and exists for the same
+   * reason: a caller that has just watched a provider fail needs its retry to
+   * land elsewhere. Without it, every consumer of this resolver — fix-gen among
+   * them — is permanently pinned to the first provider the selector picks, no
+   * matter how reliably it fails.
+   */
+  excludeProviders?: readonly string[];
 
   /**
    * When `true`, the resolver skips the provider-registry defaultModel lookup

package/src/operations/llm.ts

@@ -164,7 +164,9 @@ export type CredentialSourceWire =
   | 'cred-file'
   | 'claude-creds'
   | 'global-config'
-  | 'project-config';
+  | 'project-config'
+  /** Keyless local inference daemon detected at runtime (T12082). */
+  | 'local-daemon';
 
 /**
  * Authentication scheme used when sending the credential to the provider.
@@ -223,6 +225,22 @@ export interface CredentialMetadataWire {
   source: CredentialSourceWire | undefined;
   /** Scheme used to present the credential to the provider. */
   authType: AuthTypeWire;
+  /**
+   * Custom API endpoint this credential targets, when it has one.
+   *
+   * NOT a secret — an endpoint URL — so it belongs on the metadata wire rather
+   * than behind the sealed handle. It is load-bearing: without it a consumer
+   * building a transport cannot learn that a credential points at a local or
+   * proxied endpoint, and silently falls back to the vendor's public API.
+   *
+   * T12081: `role-executor` set `baseUrl` from `deriveApiWire(provider)` — the
+   * provider DEFAULT — because this field did not exist. An Ollama credential
+   * carrying `http://localhost:11434/v1` was rewritten to `api.openai.com` and
+   * rejected 401; the same held for LM Studio, vLLM, OpenRouter and Azure.
+   * Every custom-endpoint credential resolved correctly, then called the wrong
+   * host.
+   */
+  baseUrl?: string | null;
 }
 
 // ============================================================================
@@ -365,6 +383,19 @@ export interface ResolveLLMForRoleOptions {
    * @task T11759
    */
   profileOverride?: string;
+  /**
+   * Providers to skip during this resolution (T12082).
+   *
+   * Set by the caller after a provider has already failed for this call, so
+   * the retry lands somewhere else. Applies to EVERY tier including config
+   * pins: a pinned provider that just returned a terminal error is not a
+   * better answer for having been pinned.
+   *
+   * Empty/absent leaves resolution completely unchanged.
+   *
+   * @task T12082
+   */
+  excludeProviders?: readonly string[];
 }
 
 // ============================================================================

package/src/spawn-types.ts

@@ -18,6 +18,15 @@ export type Provider = string;
  * CAAMP-compatible spawn options (inlined for zero-dep contracts).
  */
 export interface CAAMPSpawnOptions {
+  /**
+   * Capacity-aware routing hint — the id of the least-loaded registered agent
+   * (Wave 6-C/D). Declared explicitly because `spawn-ops.ts` both writes it
+   * and reads it back for the `SubagentStart`/`SubagentStop` payloads; under
+   * the bare index signature it resolved to `unknown`, so
+   * `options?.preferredAgent ?? \`worker-${taskId}\`` widened to `{}` and the
+   * agentId silently lost its type. @task T12071
+   */
+  preferredAgent?: string;
   [key: string]: unknown;
 }
 
@@ -79,6 +88,17 @@ export interface CLEOSpawnResult extends CAAMPSpawnResult {
     durationMs?: number;
   };
 
+  /**
+   * Terminal (or in-flight) state of the spawned agent.
+   *
+   * Declared explicitly because `spawn-ops.ts` reads `result.status` to build
+   * the `SubagentStop` hook payload. Inherited from `CAAMPSpawnResult`'s bare
+   * `[key: string]: unknown` it resolved to `unknown`, so the value flowed
+   * into a typed payload field unchecked — and it does not even share that
+   * field's vocabulary ('completed' here vs 'complete' there). @task T12071
+   */
+  status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+
   /** Reference to manifest entry if output was captured */
   manifestEntryId?: string;
 }

package/src/task.ts

@@ -192,7 +192,23 @@ export type EvidenceAtom =
       failCount: number;
       skipCount: number;
     }
-  | { kind: 'tool'; tool: string; exitCode: number; stdoutTail: string }
+  | {
+      kind: 'tool';
+      tool: string;
+      exitCode: number;
+      stdoutTail?: string;
+      /**
+       * The project has no such toolchain, so the gate is satisfied by absence
+       * rather than by a run (T12083).
+       *
+       * Recorded explicitly so the audit trail never implies a tool ran that
+       * did not. Only ever set for a GUESSED language default — a command
+       * declared in `project-context.json` is always executed.
+       */
+      notApplicable?: boolean;
+      /** Why the tool was judged inapplicable. Present iff `notApplicable`. */
+      reason?: string;
+    }
   | { kind: 'url'; url: string }
   | { kind: 'note'; note: string }
   | { kind: 'override'; reason: string }