@cleocode/contracts 2026.10.27 → 2026.11.1-canary.3

package/src/__tests__/acceptance-gate.test.ts

@@ -193,12 +193,14 @@ describe('CommandGate schema', () => {
   it('round-trips a minimal command gate', () => {
     const input = {
       kind: 'command' as const,
-      cmd: 'cleo doctor',
+      cmd: 'cleo',
+      args: ['doctor'],
       description: 'cleo doctor must exit 0',
     };
     const result = commandGateSchema.parse(input);
     expect(result.kind).toBe('command');
-    expect(result.cmd).toBe('cleo doctor');
+    expect(result.cmd).toBe('cleo');
+    expect(result.args).toEqual(['doctor']);
     // exitCode defaults to undefined (not set in schema default)
     expect(result.exitCode).toBeUndefined();
   });
@@ -370,12 +372,23 @@ describe('acceptanceGateSchema (discriminated union)', () => {
   it('routes command gate by kind', () => {
     const result = acceptanceGateSchema.parse({
       kind: 'command',
-      cmd: 'pnpm doctor',
+      cmd: 'pnpm',
+      args: ['doctor'],
       description: 'doctor must succeed',
     });
     expect(result.kind).toBe('command');
   });
 
+  it('parse still accepts a legacy stored command gate whose cmd carries arguments (T14155)', () => {
+    // Writes refuse this shape (cleo req add / replace); reading a stored one never does.
+    const result = acceptanceGateSchema.parse({
+      kind: 'command',
+      cmd: 'pnpm doctor',
+      description: 'doctor must succeed',
+    });
+    expect(result.kind === 'command' && result.cmd).toBe('pnpm doctor');
+  });
+
   it('routes lint gate by kind', () => {
     const result = acceptanceGateSchema.parse({
       kind: 'lint',

package/src/__tests__/evidence-atom-schema.test.ts

@@ -32,7 +32,7 @@ describe('EvidenceAtomSchema (T10337)', () => {
     // Verify the shared constant is in sync with the zod discriminated union.
     // The discriminated union keys are 'commit','files','test-run','qa-run',
     // 'tool','url','note','decision','pr','ci','loc-drop','callsite-coverage',
-    // 'satisfies' ('qa-run': T13427).
+    // 'satisfies' ('qa-run': T13427), 'deploy' (T14083), 'ci-run' (T14149).
     const expected = [
       'commit',
       'files',
@@ -44,6 +44,8 @@ describe('EvidenceAtomSchema (T10337)', () => {
       'decision',
       'pr',
       'ci',
+      'ci-run',
+      'deploy',
       'loc-drop',
       'callsite-coverage',
       'satisfies',

package/src/__tests__/memory-wire-shapes.test.ts

@@ -68,6 +68,7 @@ type _BrainCompactHitShape = {
   bm25Score?: number;
   _next?: Record<string, string>;
   scope?: 'project' | 'global';
+  docs?: string[];
 };
 
 type _AssertBrainCompactHitPinned = AssertEquals1<Equals<BrainCompactHit, _BrainCompactHitShape>>;
@@ -99,6 +100,7 @@ type _SearchBrainCompactResultShape = {
   results: BrainCompactHit[];
   total: number;
   tokensEstimated: number;
+  taskDocs?: Array<{ taskId: string; docs: string[] }>;
 };
 
 type _AssertSearchResultPinned = AssertEquals1<

package/src/acceptance-gate-schema.ts

@@ -34,6 +34,11 @@ export const gateBaseSchema = z.object({
   advisory: z.boolean().optional(),
   /** Per-gate timeout override in milliseconds. */
   timeoutMs: z.number().int().positive().optional(),
+  /** Declared evidence repository the gate runs in (T14078). */
+  repo: z
+    .string()
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/)
+    .optional(),
 });
 
 // ─── File assertion schemas ───────────────────────────────────────────────────

package/src/acceptance-gate.ts

@@ -122,6 +122,15 @@ export interface GateBase {
    * covers only the surrounding bookkeeping, never a gate (T12621).
    */
   timeoutMs?: number;
+
+  /**
+   * Name of an evidence repository the project declares in
+   * `.cleo/project-context.json` (`evidence.repositories`, T14078): the gate
+   * runs in that checkout, its inputs are captured there and it is
+   * revalidated there. A name the project does not declare is refused.
+   * Absent, the gate runs in the task's evidence tree.
+   */
+  repo?: string;
 }
 
 // ─── Variants ────────────────────────────────────────────────────────────────

package/src/data-accessor.ts

@@ -743,6 +743,14 @@ export interface DataAccessor {
    */
   getAcRows(taskId: string): Promise<AcRow[]>;
 
+  /**
+   * Read the AC rows of many tasks in bulk (ordered by task, then ordinal),
+   * for whole-store scans such as `cleo doctor --coherence` (T12883). Optional:
+   * callers fall back to {@link getAcRows} per task when it is absent.
+   * @task T12883
+   */
+  getAcRowsForTasks?(taskIds: readonly string[]): Promise<AcRow[]>;
+
   /**
    * Read `evidence_ac_bindings` rows whose `ac_id` ∈ the given set.
    * Powers the AC-coverage gate (T10509). Returns the empty array when

package/src/dependency.ts

@@ -71,6 +71,8 @@ export interface DependencyCheckResult {
   error?: string;
   /** Actionable fix suggestion to show the user when `healthy` is `false`. */
   suggestedFix?: string;
+  /** A caveat on a healthy result, e.g. a version that could not be checked (T14166). */
+  note?: string;
 }
 
 /**

package/src/dispatch/operations-registry.ts

@@ -8727,6 +8727,13 @@ export const OPERATIONS: OperationDef[] = [
         required: false,
         description: 'Age threshold in days for the stale-drafts check (default 30)',
       },
+      {
+        name: 'only',
+        type: 'string' as const,
+        required: false,
+        description:
+          'Comma-separated repair classes to scope the plan (and apply) to, e.g. publication-ledger-drift (T14174)',
+      },
     ],
   },
   // ── docs.triage (T13446 — Epic T13340 / Saga T13339) ──────────────────────
@@ -8780,6 +8787,29 @@ export const OPERATIONS: OperationDef[] = [
     requiredParams: [],
     params: [],
   },
+  // ── docs.rot (T14111 — Epic T14106) ──────────────────────────────────────
+  {
+    gateway: 'query',
+    domain: 'docs',
+    operation: 'rot',
+    description:
+      'docs.rot (query) — docs-rot report from git alone: docs whose covers: code changed ' +
+      'after them (stale), duplicate docs, and orphaned docs (dead covers globs, ' +
+      'unreferenced docs/ files). changed:<base>..<head> also lists the docs that merged ' +
+      'change left stale. Read-only.',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [
+      {
+        name: 'changed',
+        type: 'string' as const,
+        required: false,
+        description: 'Git range <base>..<head> of a merged change to flag docs for',
+      },
+    ],
+  },
   {
     gateway: 'mutate',
     domain: 'docs',
@@ -8816,6 +8846,13 @@ export const OPERATIONS: OperationDef[] = [
         required: false,
         description: 'Age threshold in days for the stale-drafts check (default 30)',
       },
+      {
+        name: 'only',
+        type: 'string' as const,
+        required: false,
+        description:
+          'Comma-separated repair classes to scope the plan (and apply) to, e.g. publication-ledger-drift (T14174)',
+      },
     ],
   },
   // ── docs.migrate (T13360 — Epic T13340 / Saga T13339) ─────────────────────
@@ -8836,6 +8873,97 @@ export const OPERATIONS: OperationDef[] = [
     requiredParams: [],
     params: [],
   },
+  // ── docs.modernize (T14113 — Epic T14106) ─────────────────────────────────
+  {
+    gateway: 'mutate',
+    domain: 'docs',
+    operation: 'modernize',
+    description:
+      'docs.modernize (mutate) — turn a messy docs folder into clean, linked CleoDocs. Dry run ' +
+      'by default: proposes per file a kind, a stable slug (no task, session or date tokens) ' +
+      'and keep/rename/merge-into/delete with reasons and any System One judgment. --apply ' +
+      'stores, merges, supersedes, moves files and writes wikilink edges with a receipt; ' +
+      '--rollback <runId> reverses a run.',
+    tier: 1,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [
+      {
+        name: 'path',
+        type: 'string' as const,
+        required: false,
+        description: 'Folder to modernize (required unless --rollback)',
+      },
+      {
+        name: 'apply',
+        type: 'boolean' as const,
+        required: false,
+        description: 'Execute the plan (default: dry run, nothing written)',
+      },
+      {
+        name: 'planFile',
+        type: 'string' as const,
+        required: false,
+        description: 'Apply this saved plan JSON verbatim',
+      },
+      {
+        name: 'out',
+        type: 'string' as const,
+        required: false,
+        description: 'Save the plan JSON to this path',
+      },
+      {
+        name: 'rollback',
+        type: 'string' as const,
+        required: false,
+        description: 'Roll back the apply run with this id',
+      },
+      {
+        name: 'exclude',
+        type: 'string' as const,
+        required: false,
+        description: 'Extra folder names to skip, comma-separated',
+      },
+      {
+        name: 'overrides',
+        type: 'string' as const,
+        required: false,
+        description: 'Reviewer decisions JSON keyed by path (DocsModernizeOverrides)',
+      },
+      {
+        name: 'kind',
+        type: 'string' as const,
+        required: false,
+        description: 'Use this kind for every file instead of classifying',
+      },
+      {
+        name: 'storeOnly',
+        type: 'boolean' as const,
+        required: false,
+        description: 'Ingest every file into the store and leave the folder untouched',
+      },
+      {
+        name: 'allowDirty',
+        type: 'boolean' as const,
+        required: false,
+        description: 'Apply even when the root is not a clean git checkout',
+      },
+      {
+        name: 'wikilinks',
+        type: 'boolean' as const,
+        required: false,
+        description:
+          'Rewrite relative links to planned docs as [[slug]] wikilinks (default: keep markdown links, re-pointed at the new paths)',
+      },
+      {
+        name: 'store',
+        type: 'boolean' as const,
+        required: false,
+        description: 'Modernize the docs already in the store instead of a folder',
+      },
+    ],
+  },
   // ── docs.generate (T798) ─────────────────────────────────────────────────
   {
     gateway: 'query',
@@ -9782,6 +9910,106 @@ export const OPERATIONS: OperationDef[] = [
     ] satisfies ParamDef[],
   },
 
+  // release mutate: cut (T14102 — one-command release from the newest green
+  // default-branch commit; replaces plan → open → bump-PR → hand tag).
+  {
+    gateway: 'mutate',
+    domain: 'release',
+    operation: 'cut',
+    description:
+      'release.cut (mutate) — tag the newest default-branch commit with green CI as v<version> once confirmed with --yes (D11211/D11212); release.yml writes the CHANGELOG from changesets and publishes. Without --yes it reports the commit, notes, packages and task status and prints the confirm command (T14102).',
+    tier: 1,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['version'],
+    params: [
+      {
+        name: 'version',
+        type: 'string',
+        required: true,
+        description: 'Release version (accepts v2026.10.28 or 2026.10.28)',
+        cli: { positional: true },
+      },
+      {
+        name: 'sha',
+        type: 'string',
+        required: false,
+        description: 'Pin the commit instead of the newest green one; it must itself be green',
+      },
+      {
+        name: 'lead',
+        type: 'string',
+        required: false,
+        description: 'Markdown file that leads the notes (Update now + Highlights)',
+      },
+      {
+        name: 'dryRun',
+        type: 'boolean',
+        required: false,
+        description: 'Report the commit, notes, packages and tasks without creating the tag',
+      },
+      {
+        name: 'yes',
+        type: 'boolean',
+        required: false,
+        description:
+          'Create the tag (D11212): the version typed on the controlling terminal (/dev/tty), or a standing release authorization (T14141), allows it. Without it the cut only reports and prints the confirm command',
+      },
+    ] satisfies ParamDef[],
+  },
+
+  // release mutate: write-changelog (T14102 — CHANGELOG section from the
+  // changesets since the previous tag; run by release.yml on the tagged checkout).
+  {
+    gateway: 'mutate',
+    domain: 'release',
+    operation: 'write-changelog',
+    description:
+      'release.write-changelog (mutate) — write the ## [VERSION] CHANGELOG.md section from the changesets added since the previous release tag, led by the tag annotation; leaves an existing section untouched (T14102).',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['version'],
+    params: [
+      {
+        name: 'version',
+        type: 'string',
+        required: true,
+        description: 'Release version (accepts v2026.10.28 or 2026.10.28)',
+        cli: { positional: true },
+      },
+      {
+        name: 'ref',
+        type: 'string',
+        required: false,
+        description: 'Commit the release was cut from (default: tag v<version>, else HEAD)',
+      },
+    ] satisfies ParamDef[],
+  },
+
+  // release query: verify-tag (T14102 — release.yml refuses to publish a tag
+  // that is not a green first-parent commit of the default branch).
+  {
+    gateway: 'query',
+    domain: 'release',
+    operation: 'verify-tag',
+    description:
+      'release.verify-tag (query) — refuse a release tag whose commit is not a first-parent commit of origin/main with every required check (release.prRequiredWorkflows, app-pinned) green on its push run. Run by release.yml before publishing (T14102).',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['version'],
+    params: [
+      {
+        name: 'version',
+        type: 'string',
+        required: true,
+        description: 'Release version whose tag is checked (accepts v2026.10.28 or 2026.10.28)',
+        cli: { positional: true },
+      },
+    ] satisfies ParamDef[],
+  },
+
   // release query: validate-changelog (T9937 / Saga T9862 — canonical CHANGELOG
   // header validator that replaces the brittle inline grep step in
   // .github/workflows/release.yml). Read-only — exposed only under the query