@cleocode/contracts 2026.5.111 → 2026.5.112

package/dist/evidence-atom-schema.d.ts

@@ -0,0 +1,407 @@
+/**
+ * Zod schema + gate-to-atom mapping for the ADR-051 evidence atom grammar.
+ *
+ * `cleo verify <task-id> --evidence "<atoms>"` accepts a semicolon-delimited
+ * list of evidence atoms. Each atom carries a kind prefix and a payload. The
+ * grammar lives in three places today:
+ *
+ *   1. {@link EvidenceAtomSchema} — Zod discriminated union covering every
+ *      parseable atom shape (this file).
+ *   2. {@link GATE_EVIDENCE_REQUIREMENTS} — gate → satisfying atom-combination
+ *      map (this file).
+ *   3. `packages/core/src/tasks/evidence.ts` — runtime parser + filesystem /
+ *      git / tool validators. The runtime parser delegates to
+ *      {@link parseEvidenceString} below for the syntactic split.
+ *
+ * The schema is exposed for LLM agents and IDE tooling that want to validate
+ * an evidence string client-side BEFORE invoking `cleo verify`. The CLI
+ * runtime continues to perform the full filesystem-aware validation pass
+ * because Zod cannot check that a commit SHA is reachable or that a file
+ * exists on disk.
+ *
+ * The atom shapes here mirror the `ParsedAtom` union in
+ * `packages/core/src/tasks/evidence.ts` exactly. Behavior parity with the
+ * pre-T10337 ad-hoc parser is required — see the T10337 test suite for the
+ * full parity matrix.
+ *
+ * @task T10337
+ * @saga T10326
+ * @adr ADR-051
+ */
+import { z } from 'zod';
+import type { VerificationGate } from './task.js';
+/**
+ * `commit:<sha>` atom — references a git commit by full or short SHA.
+ *
+ * Format: `commit:<7-40 hex chars>`. The schema accepts any 7-40-character
+ * lowercase hex SHA; the runtime validator additionally checks reachability
+ * from the task branch and the AC-file content-intersect rule (T9245).
+ *
+ * @task T832
+ */
+export declare const commitAtomSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"commit">;
+    sha: z.ZodString;
+}, z.core.$strip>;
+/**
+ * `files:<p1,p2,...>` atom — list of file paths that the task touched.
+ *
+ * Format: `files:<comma-separated paths>`. The runtime validator additionally
+ * stats each path and records its sha256.
+ *
+ * @task T832
+ */
+export declare const filesAtomSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"files">;
+    paths: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * `test-run:<path>` atom — path to a structured test runner JSON output
+ * (vitest, jest, pytest, cargo-nextest, etc.).
+ *
+ * Format: `test-run:<absolute or project-relative path>`. The runtime validator
+ * loads the file, parses the JSON, and rejects when failedTests > 0 or
+ * totalTests === 0.
+ *
+ * @task T832
+ */
+export declare const testRunAtomSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"test-run">;
+    path: z.ZodString;
+}, z.core.$strip>;
+/**
+ * `tool:<name>` atom — runs a project-resolved canonical tool and accepts
+ * exit-code 0.
+ *
+ * Format: `tool:<canonical name or legacy alias>`. Canonical names: `test`,
+ * `build`, `lint`, `typecheck`, `audit`, `security-scan`. Legacy aliases
+ * (`pnpm-test`, `tsc`, `biome`, `cargo-test`, `pytest`, …) still resolve via
+ * the runtime resolver (ADR-061 / T1534).
+ *
+ * @task T832
+ * @task T1534
+ */
+export declare const toolAtomSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"tool">;
+    tool: z.ZodString;
+}, z.core.$strip>;
+/**
+ * `url:<href>` atom — soft evidence pointing to an external artifact (docs,
+ * dashboard, etc.).
+ *
+ * Format: `url:<http(s)://...>`. The runtime validator requires the
+ * `http://` or `https://` scheme.
+ *
+ * @task T832
+ */
+export declare const urlAtomSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"url">;
+    url: z.ZodString;
+}, z.core.$strip>;
+/**
+ * `note:<text>` atom — free-form note used for soft evidence and waivers.
+ *
+ * Format: `note:<1-512 chars>`. The runtime validator caps the note at 512
+ * characters to keep the gate-evidence record bounded.
+ *
+ * @task T832
+ */
+export declare const noteAtomSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"note">;
+    note: z.ZodString;
+}, z.core.$strip>;
+/**
+ * `decision:<id>` atom — references a `brain_decisions` row that IS the
+ * canonical artifact for a decision-only task. Satisfies the `implemented`
+ * gate when combined with `files:` pointing to a research note or with
+ * `note:` (T1875).
+ *
+ * Format: `decision:<id>` (e.g. `decision:D-arch-001`). The runtime validator
+ * looks up the row and requires `confirmation_state` ∈ {`accepted`,
+ * `proposed`}.
+ *
+ * @task T1875
+ */
+export declare const decisionAtomSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"decision">;
+    decisionId: z.ZodString;
+}, z.core.$strip>;
+/**
+ * `pr:<number>` atom — references a GitHub PR by number. Satisfies BOTH
+ * `testsPassed` and `qaPassed` simultaneously when the PR is MERGED and every
+ * required-workflow check is green (T9764). Extended in T9838 to satisfy
+ * `implemented` because the merge commit IS the landing artifact.
+ *
+ * Format: `pr:<positive integer>` (e.g. `pr:357`).
+ *
+ * @task T9764
+ * @task T9838
+ */
+export declare const prAtomSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"pr">;
+    prNumber: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * `loc-drop:<fromLines>:<toLines>` atom — proves that a migrated engine shed
+ * lines. Required for the `implemented` gate when the task carries the
+ * `engine-migration` label (T1604).
+ *
+ * Format: `loc-drop:<non-negative integer>:<non-negative integer>`.
+ * The schema admits any non-negative pair; the runtime validator additionally
+ * requires `fromLines > 0` and `toLines <= fromLines`.
+ *
+ * @task T1604
+ */
+export declare const locDropAtomSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"loc-drop">;
+    fromLines: z.ZodNumber;
+    toLines: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * `callsite-coverage:<symbol>:<sourcePath>` atom — proves that an exported
+ * symbol has ≥1 production callsite outside its own source file, test files,
+ * and dist directories. Required for the `implemented` gate when the task
+ * carries the `callsite-coverage` label (T1605).
+ *
+ * @task T1605
+ */
+export declare const callsiteCoverageAtomSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"callsite-coverage">;
+    symbolName: z.ZodString;
+    relativeSourcePath: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Zod discriminated union covering every parseable evidence atom prefix.
+ *
+ * Use `EvidenceAtomSchema.safeParse(atom)` to validate a single atom client-
+ * side BEFORE invoking `cleo verify`. The runtime parser in
+ * `packages/core/src/tasks/evidence.ts` performs filesystem/git/tool checks
+ * on top of this syntactic schema.
+ *
+ * Atom kinds:
+ *   - `commit`             — git commit SHA (T832)
+ *   - `files`              — touched file paths (T832)
+ *   - `test-run`           — structured test runner JSON (T832)
+ *   - `tool`               — project-resolved tool exit code (T832 / T1534)
+ *   - `url`                — soft external pointer (T832)
+ *   - `note`               — free-form note (T832)
+ *   - `decision`           — brain_decisions row reference (T1875)
+ *   - `pr`                 — merged-PR retroactive proof (T9764 / T9838)
+ *   - `loc-drop`           — engine-migration LOC reduction (T1604)
+ *   - `callsite-coverage`  — exported-symbol production callsite (T1605)
+ *
+ * @task T10337
+ * @adr ADR-051
+ */
+export declare const EvidenceAtomSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"commit">;
+    sha: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"files">;
+    paths: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"test-run">;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"tool">;
+    tool: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"url">;
+    url: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"note">;
+    note: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"decision">;
+    decisionId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"pr">;
+    prNumber: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"loc-drop">;
+    fromLines: z.ZodNumber;
+    toLines: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"callsite-coverage">;
+    symbolName: z.ZodString;
+    relativeSourcePath: z.ZodString;
+}, z.core.$strip>], "kind">;
+/**
+ * Inferred TypeScript type for a parsed evidence atom.
+ *
+ * This is the pre-validation shape emitted by {@link parseEvidenceString}
+ * — distinct from the post-validation `EvidenceAtom` in `./task.ts` which
+ * carries fields populated by the runtime validator (sha256, exitCode, etc.).
+ *
+ * @task T10337
+ */
+export type EvidenceAtom = z.infer<typeof EvidenceAtomSchema>;
+/** Discriminant union of every atom kind accepted by {@link EvidenceAtomSchema}. */
+export type EvidenceAtomKind = EvidenceAtom['kind'];
+/**
+ * Per-gate evidence requirement spec.
+ *
+ * Each entry of `oneOf` is a satisfying atom-combination — the gate is
+ * satisfied IFF EVERY kind listed in at least ONE of the combinations is
+ * present among the supplied atoms.
+ *
+ * A single-element combination `['pr']` means "one `pr:` atom alone
+ * satisfies the gate". A two-element combination `['commit', 'files']` means
+ * "both a `commit:` atom AND a `files:` atom must be present".
+ *
+ * @task T10337
+ * @adr ADR-051 §2.3
+ */
+export interface GateEvidenceRequirement {
+    /** Alternative satisfying combinations — ANY one is sufficient. */
+    oneOf: ReadonlyArray<ReadonlyArray<EvidenceAtomKind>>;
+}
+/**
+ * Mapping from each {@link VerificationGate} to its satisfying atom
+ * combinations. Mirrors the legacy `GATE_EVIDENCE_MINIMUMS` table in
+ * `packages/core/src/tasks/evidence.ts` exactly — behavior parity required
+ * by T10337.
+ *
+ * ## Why two alternatives for `implemented`?
+ *
+ * The `implemented` gate accepts six different evidence shapes:
+ *
+ *   - `[commit, files]`   — standard: commit SHA + touched file list.
+ *   - `[commit, note]`    — deletion-safe: commit SHA + descriptive note
+ *                           (when the implementation deleted files there
+ *                           are none left to anchor `files:`).
+ *   - `[decision, files]` — decision-only task: brain_decisions row +
+ *                           research-note file (T1875).
+ *   - `[decision, note]`  — decision-only task without research note.
+ *   - `[pr]`              — merged-PR retroactive proof (T9838 extension
+ *                           of T9764).
+ *
+ * ## Why is `qaPassed` listed as `['tool']` not `['tool', 'tool']`?
+ *
+ * The pre-T10337 runtime enforced "at least one atom of kind `tool` is
+ * present" — it did NOT count distinct tool names. The convention `tool:lint`
+ * + `tool:typecheck` is documented in AGENTS.md as best-practice but the
+ * gate is satisfied by a single tool atom (e.g. `tool:test` when test
+ * already runs lint + typecheck pre-flight). Behavior parity requires that
+ * single-tool atoms continue to pass.
+ *
+ * @task T10337
+ * @adr ADR-051 §2.3
+ */
+export declare const GATE_EVIDENCE_REQUIREMENTS: Readonly<Record<VerificationGate, GateEvidenceRequirement>>;
+/**
+ * Result of {@link validateEvidenceForGate}.
+ *
+ * Success carries no extra payload (the caller already holds the atom list).
+ * Failure carries a human-readable message in the legacy
+ * `Gate '<gate>' requires evidence: [<combo>] OR [<combo>]` format so error
+ * surfaces (E_EVIDENCE_INSUFFICIENT) read identically across the CLI and any
+ * client-side validator built on top of this schema.
+ */
+export type EvidenceValidationResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Format the satisfying-combinations spec for a gate as the legacy
+ * `[commit AND files] OR [pr]` string used in CLI error messages.
+ *
+ * Exposed so consumers can render the same hint text without re-computing it.
+ *
+ * @task T10337
+ */
+export declare function formatGateRequirement(gate: VerificationGate): string;
+/**
+ * Check whether a set of parsed atoms satisfies the requirement spec for
+ * `gate`.
+ *
+ * Returns `{ ok: true }` when ANY combination in `GATE_EVIDENCE_REQUIREMENTS[gate].oneOf`
+ * is fully present in `atoms` (matched by kind). Returns
+ * `{ ok: false, message }` otherwise — the message matches the legacy
+ * `checkGateEvidenceMinimum()` format byte-for-byte so error surfaces do not
+ * regress.
+ *
+ * Atoms must already be parsed (via {@link parseEvidenceString} or
+ * {@link EvidenceAtomSchema}); the helper does NOT re-validate the atom
+ * payload. Use {@link EvidenceAtomSchema.safeParse} first if the input came
+ * from an untrusted source.
+ *
+ * @param gate - Verification gate being checked.
+ * @param atoms - Already-parsed evidence atoms.
+ * @returns Pass / fail with a human-readable failure message.
+ *
+ * @example
+ * ```ts
+ * const atoms = parseEvidenceString('commit:abc1234;files:src/foo.ts');
+ * validateEvidenceForGate('implemented', atoms); // { ok: true }
+ * validateEvidenceForGate('testsPassed', atoms);
+ * // { ok: false, message: "Gate 'testsPassed' requires evidence: [test-run] OR [tool] OR [pr]" }
+ * ```
+ *
+ * @task T10337
+ * @adr ADR-051 §2.3
+ */
+export declare function validateEvidenceForGate(gate: VerificationGate, atoms: ReadonlyArray<{
+    kind: EvidenceAtomKind;
+}>): EvidenceValidationResult;
+/**
+ * Error class thrown by {@link parseEvidenceString} when the input is
+ * malformed. Carries a {@link reason} suitable for the CLI `fix:` hint.
+ *
+ * Pure data — no dependency on `@cleocode/contracts/errors` (which would
+ * pull the CleoError import surface into every consumer that just wants
+ * syntactic validation).
+ *
+ * @task T10337
+ */
+export declare class EvidenceParseError extends Error {
+    /** Hint text suitable for an `fix:` message in the CLI surface. */
+    readonly fix: string;
+    constructor(message: string, fix: string);
+}
+/**
+ * Parse the raw CLI `--evidence` string into structured atoms.
+ *
+ * Syntax:
+ * ```
+ * evidence-list := atom (';' atom)*
+ * atom          := kind ':' payload
+ * ```
+ *
+ * The payload format depends on `kind`:
+ *
+ *   - `files`             — comma-separated paths
+ *   - `loc-drop`          — `<fromLines>:<toLines>` (two integers)
+ *   - `callsite-coverage` — `<symbolName>:<relativeSourcePath>`
+ *   - `pr`                — positive integer
+ *   - everything else     — opaque payload string until the next `;`
+ *
+ * A `state:MERGED` modifier may follow a `pr:<num>` atom and is consumed
+ * in-place (no separate atom is emitted) — see T9838. Any other usage of
+ * `state:` is rejected.
+ *
+ * Whitespace surrounding the `;` separators and around `kind`/`payload` is
+ * trimmed. Empty chunks are skipped (consecutive `;;` is tolerated).
+ *
+ * @param raw - Raw `--evidence` string.
+ * @returns Parsed atoms ready for {@link validateEvidenceForGate} or for
+ *   the runtime validator in `packages/core/src/tasks/evidence.ts`.
+ * @throws {@link EvidenceParseError} when the input is malformed.
+ *
+ * @example
+ * ```ts
+ * parseEvidenceString('commit:abc1234;files:src/foo.ts,src/bar.ts;tool:lint');
+ * // [
+ * //   { kind: 'commit', sha: 'abc1234' },
+ * //   { kind: 'files', paths: ['src/foo.ts', 'src/bar.ts'] },
+ * //   { kind: 'tool', tool: 'lint' },
+ * // ]
+ * ```
+ *
+ * @task T10337
+ * @adr ADR-051
+ */
+export declare function parseEvidenceString(raw: string): EvidenceAtom[];
+//# sourceMappingURL=evidence-atom-schema.d.ts.map

package/dist/evidence-atom-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-atom-schema.d.ts","sourceRoot":"","sources":["../src/evidence-atom-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAMlD;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB;;;iBAG3B,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;;;iBAG1B,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB;;;iBAG5B,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc;;;iBAGzB,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa;;;iBAMxB,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;;iBAMzB,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB;;;iBAG7B,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY;;;iBAGvB,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB;;;;iBAI5B,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B;;;;iBAMrC,CAAC;AAMH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAW7B,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,oFAAoF;AACpF,MAAM,MAAM,gBAAgB,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;AAMpD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,uBAAuB;IACtC,mEAAmE;IACnE,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,gBAAgB,CAAC,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAC/C,MAAM,CAAC,gBAAgB,EAAE,uBAAuB,CAAC,CAiBjD,CAAC;AAMH;;;;;;;;GAQG;AACH,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAGpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC,GAC/C,wBAAwB,CAe1B;AAED;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,mEAAmE;IACnE,SAAgB,GAAG,EAAE,MAAM,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAKzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE,CA8J/D"}