@cleocode/contracts 2026.7.2 → 2026.8.2

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/evidence-atom-schema.ts

@@ -33,6 +33,52 @@ import { z } from 'zod';
 
 import type { VerificationGate } from './task.js';
 
+// ---------------------------------------------------------------------------
+// Known atom kinds — shared typed constant for boundary detection + error
+// messages.  Prefer this list over duplicated regex strings.
+// ---------------------------------------------------------------------------
+
+/**
+ * Every evidence atom kind recognized by the parser.
+ *
+ * Defines the exhaustive set of `kind:` prefixes accepted by
+ * {@link parseEvidenceString}. Derived from {@link EvidenceAtomSchema}'s
+ * discriminated union. Shared so boundary-splitting regexes, documentation,
+ * and error messages always agree without duplicating the literal list.
+ *
+ * Note: `state` is a recognized parser prefix (modifier for `pr:`) but is
+ * NOT a standalone {@link EvidenceAtom} kind — it is consumed in-place by the
+ * parser and never emitted as an atom. The boundary regex MUST include it so
+ * `pr:357;state:MERGED` splits correctly.
+ *
+ * @task T12030
+ */
+export const EVIDENCE_ATOM_KINDS = [
+  'commit',
+  'files',
+  'test-run',
+  'tool',
+  'url',
+  'note',
+  'decision',
+  'pr',
+  'loc-drop',
+  'callsite-coverage',
+  'satisfies',
+] as const satisfies ReadonlyArray<EvidenceAtom['kind']>;
+
+/** Parser-level prefixes — {@link EVIDENCE_ATOM_KINDS} + `state` modifier. */
+const PARSER_PREFIXES = [...EVIDENCE_ATOM_KINDS, 'state'] as const;
+
+/**
+ * Regex matching a `;` ONLY when the next non-whitespace token is a known
+ * atom kind prefix followed by `:`.  Used instead of a naive `split(';')` so
+ * semicolons inside `note:` payloads are preserved.
+ *
+ * @task T12030
+ */
+const KIND_BOUNDARY_REGEX = new RegExp(`;(?=\\s*(?:${PARSER_PREFIXES.join('|')})\\s*:)`, 'g');
+
 // ---------------------------------------------------------------------------
 // Per-atom Zod schemas
 // ---------------------------------------------------------------------------
@@ -714,8 +760,9 @@ export function parseEvidenceString(raw: string): EvidenceAtom[] {
     );
   }
   const chunks = raw
-    .split(';')
+    .split(KIND_BOUNDARY_REGEX)
     .map((s) => s.trim())
+    .map((s) => s.replace(/^;+/, '')) // strip leading separator artifacts (;;commit: → commit:)
     .filter(Boolean);
   if (chunks.length === 0) {
     throw new EvidenceParseError(
@@ -734,7 +781,11 @@ export function parseEvidenceString(raw: string): EvidenceAtom[] {
       );
     }
     const kind = chunk.slice(0, colon).trim();
-    const payload = chunk.slice(colon + 1).trim();
+    const rawPayload = chunk.slice(colon + 1).trim();
+    // Strip trailing separator semicolons from non-note atoms (the old naive
+    // split consumed them as empty chunks).  Note payloads preserve every
+    // character, including trailing ';', so they act as real punctuation.
+    const payload = kind === 'note' ? rawPayload : rawPayload.replace(/;+$/, '');
     switch (kind) {
       case 'commit':
         atoms.push({ kind: 'commit', sha: payload });
@@ -930,7 +981,7 @@ export function parseEvidenceString(raw: string): EvidenceAtom[] {
       default:
         throw new EvidenceParseError(
           `Unknown evidence kind: "${kind}" in atom "${chunk}"`,
-          'Valid kinds: commit, files, test-run, tool, url, note, loc-drop, callsite-coverage, decision, pr, satisfies, state',
+          `Valid kinds: ${PARSER_PREFIXES.join(', ')}`,
         );
     }
   }

package/src/index.ts

@@ -544,6 +544,7 @@ export {
   callsiteCoverageAtomSchema,
   commitAtomSchema,
   decisionAtomSchema,
+  EVIDENCE_ATOM_KINDS,
   EvidenceAtomSchema,
   EvidenceParseError,
   filesAtomSchema,
@@ -2652,4 +2653,16 @@ 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';

package/src/project-context.ts

@@ -55,6 +55,14 @@ export type FileNamingConvention = 'kebab-case' | 'snake_case' | 'camelCase' | '
 /** Module import style. */
 export type ImportStyle = 'esm' | 'commonjs' | 'mixed';
 
+/** Release and evidence behavior configured per project. */
+export interface ProjectReleaseContext {
+  /** Branches whose reachable commits may satisfy `commit:` evidence atoms. */
+  integrationBranches?: string[];
+  /** Required successful checks for `pr:` evidence atoms. */
+  prRequiredWorkflows?: string[];
+}
+
 /** Schema-compliant project context for LLM agent consumption. */
 export interface ProjectContext {
   schemaVersion: string;
@@ -91,6 +99,28 @@ export interface ProjectContext {
     commonPatterns?: string[];
     avoidPatterns?: string[];
   };
+  /** Lint command override (T12026). */
+  lint?: {
+    /** Command to run static analysis / lint checks. */
+    command?: string;
+  };
+  /** Type-check command override (T12026). */
+  typecheck?: {
+    /** Command to run type checking. */
+    command?: string;
+  };
+  /** Audit command override (T12026). */
+  audit?: {
+    /** Command to run dependency/module audit checks. */
+    command?: string;
+  };
+  /** Security-scan command override (T12026). JSON key is `security-scan`. */
+  'security-scan'?: {
+    /** Command to run security vulnerability scanning. */
+    command?: string;
+  };
+  /** Release and evidence behavior for this project. */
+  release?: ProjectReleaseContext;
 }
 
 /**