@cleocode/contracts 2026.5.92 → 2026.5.94

package/src/operations/validate.ts

@@ -277,6 +277,39 @@ export interface ValidateCanonResult {
   assertions: Array<{ passed: boolean }>;
 }
 
+/**
+ * Params for `check.canon.docs` — the T9796 docs-routing CI gate.
+ *
+ * `baseRef` defaults to `origin/main` and is overridden in CI to
+ * `origin/${{ github.base_ref }}` so PRs targeting any branch work.
+ * `candidateFiles` is a test seam — when supplied, bypasses `git diff`
+ * and treats the list as the candidate set.
+ *
+ * @task T9796 — E-DOCS-CANON-LOCKDOWN
+ */
+export interface ValidateCanonDocsParams {
+  baseRef?: string;
+  candidateFiles?: ReadonlyArray<string>;
+}
+
+/**
+ * Result envelope returned by `check.canon.docs`.
+ *
+ * @task T9796
+ */
+export interface ValidateCanonDocsResult {
+  passed: boolean;
+  baseRef: string;
+  scanned: number;
+  violations: ReadonlyArray<{
+    file: string;
+    kind: string;
+    matchedPath: string;
+    fix: string;
+  }>;
+  mode: 'enforced' | 'no-canon';
+}
+
 export interface ValidateWorkflowComplianceParams {
   since?: string;
 }
@@ -350,6 +383,7 @@ export type CheckOps = {
   readonly grade: readonly [ValidateGradeParams, ValidateGradeResult];
   readonly 'grade.list': readonly [ValidateGradeListParams, ValidateGradeListResult];
   readonly canon: readonly [ValidateCanonParams, ValidateCanonResult];
+  readonly 'canon.docs': readonly [ValidateCanonDocsParams, ValidateCanonDocsResult];
   readonly 'workflow.compliance': readonly [
     ValidateWorkflowComplianceParams,
     ValidateWorkflowComplianceResult,

package/src/release/evidence-atoms.ts

@@ -28,7 +28,14 @@ import { z } from 'zod';
  * "pr:357"`. The number is restricted to positive integers because
  * GitHub PR numbers cannot be zero or negative.
  *
+ * T9838 introduced the optional explicit-form modifier
+ * `pr:<num>;state:MERGED`. The `state` modifier is intent-documenting
+ * (the resolver always demands state === 'MERGED') and is consumed at
+ * parse time without being emitted as a separate atom. See
+ * {@link prEvidenceStateModifierSchema}.
+ *
  * @task T9764
+ * @task T9838
  */
 export interface ParsedPrEvidenceAtom {
   /** Discriminant — always `'pr'`. */
@@ -51,6 +58,37 @@ export const parsedPrEvidenceAtomSchema = z.object({
   prNumber: z.number().int().positive(),
 }) satisfies z.ZodType<ParsedPrEvidenceAtom>;
 
+/**
+ * Zod schema for the optional `state:MERGED` modifier that may follow a
+ * `pr:<num>` atom in the evidence string (T9838).
+ *
+ * The modifier is intent-documenting: the resolver always demands
+ * `state === 'MERGED'`, so emitting `state:MERGED` explicitly is a
+ * no-op assertion that proves the caller knows the contract. Only the
+ * literal string `"MERGED"` is accepted — `OPEN`, `CLOSED`, or any other
+ * value is rejected at parse time because no other state can satisfy any
+ * gate the `pr:` atom is allowed to back.
+ *
+ * The parser consumes the modifier in-place (it does NOT emit a separate
+ * atom) so downstream code never sees a free-standing `state` atom. The
+ * schema exists so external producers (e.g. a future provenance importer)
+ * can validate the literal payload before passing it to `parseEvidence`.
+ *
+ * @task T9838
+ */
+export const prEvidenceStateModifierSchema = z.object({
+  kind: z.literal('state'),
+  value: z.literal('MERGED'),
+});
+
+/**
+ * Inferred type for the explicit `state:MERGED` modifier emitted alongside
+ * a `pr:<num>` atom. See {@link prEvidenceStateModifierSchema}.
+ *
+ * @task T9838
+ */
+export type PrEvidenceStateModifier = z.infer<typeof prEvidenceStateModifierSchema>;
+
 /**
  * Raw shape returned by `gh pr view <num> --json
  * statusCheckRollup,mergeable,state,mergedAt,headRefOid`.