@cleocode/contracts 2026.5.120 → 2026.5.121

package/src/__tests__/changesets.test.ts

@@ -0,0 +1,176 @@
+/**
+ * Tests for CLEO changeset contracts and parser compatibility.
+ *
+ * @task T10480
+ * @epic T9759
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ChangesetEntrySchema } from '../changesets.js';
+
+type ParseChangesetFile = (path: string) => unknown;
+
+let tempDir: string;
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), 'cleo-changesets-contract-'));
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+function writeChangeset(filename: string, content: string): string {
+  const path = join(tempDir, filename);
+  writeFileSync(path, content, 'utf8');
+  return path;
+}
+
+async function loadParseChangesetFile(): Promise<ParseChangesetFile> {
+  const parserUrl = new URL('../../../core/src/changesets/parser.ts', import.meta.url).href;
+  const parser = (await import(parserUrl)) as { parseChangesetFile: ParseChangesetFile };
+  return parser.parseChangesetFile;
+}
+
+describe('ChangesetEntrySchema release-note metadata', () => {
+  it('accepts legacy changesets without releaseNotes unchanged', () => {
+    const legacy = {
+      id: 'T10480',
+      tasks: ['T10480'],
+      kind: 'fix',
+      summary: 'Legacy changesets still parse.',
+    };
+
+    const parsed = ChangesetEntrySchema.parse(legacy);
+
+    expect(parsed).toEqual(legacy);
+    expect(parsed.releaseNotes).toBeUndefined();
+  });
+
+  it('accepts deterministic zero-token release-note metadata', () => {
+    const entry = ChangesetEntrySchema.parse({
+      id: 't10480-release-notes',
+      tasks: ['T10480', 'T9759'],
+      kind: 'feat',
+      summary: 'Add structured release-note metadata.',
+      releaseNotes: {
+        section: 'added',
+        audience: ['operators', 'developers'],
+        scope: 'package',
+        targets: ['@cleocode/contracts', '@cleocode/core'],
+        impact: 'Release tooling can render richer notes from author-provided facts.',
+        migration: 'No migration required for legacy changesets.',
+        operatorNotes: 'No LLM, API token, or network call is required.',
+        includeInChangelog: true,
+      },
+    });
+
+    expect(entry.releaseNotes).toEqual({
+      section: 'added',
+      audience: ['operators', 'developers'],
+      scope: 'package',
+      targets: ['@cleocode/contracts', '@cleocode/core'],
+      impact: 'Release tooling can render richer notes from author-provided facts.',
+      migration: 'No migration required for legacy changesets.',
+      operatorNotes: 'No LLM, API token, or network call is required.',
+      includeInChangelog: true,
+    });
+  });
+
+  it('rejects malformed release-note metadata loudly', () => {
+    const result = ChangesetEntrySchema.safeParse({
+      id: 't10480-bad-release-notes',
+      tasks: ['T10480'],
+      kind: 'feat',
+      summary: 'Bad metadata.',
+      releaseNotes: {
+        section: 'feature',
+      },
+    });
+
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.error.issues[0]?.path).toEqual(['releaseNotes', 'section']);
+  });
+});
+
+describe('parseChangesetFile release-note metadata compatibility', () => {
+  it('parses legacy markdown changesets unchanged', async () => {
+    const parseChangesetFile = await loadParseChangesetFile();
+    const file = writeChangeset(
+      'T10480.md',
+      `---
+id: T10480
+tasks: [T10480]
+kind: fix
+summary: Legacy markdown changesets still parse unchanged.
+---
+
+Body notes survive.
+`,
+    );
+
+    expect(parseChangesetFile(file)).toEqual({
+      id: 'T10480',
+      tasks: ['T10480'],
+      kind: 'fix',
+      summary: 'Legacy markdown changesets still parse unchanged.',
+      notes: 'Body notes survive.',
+    });
+  });
+
+  it('parses new release-note metadata from markdown frontmatter', async () => {
+    const parseChangesetFile = await loadParseChangesetFile();
+    const file = writeChangeset(
+      't10480-new-metadata.md',
+      `---
+id: t10480-new-metadata
+tasks: [T10480]
+kind: feat
+summary: Parse release-note metadata.
+releaseNotes:
+  section: changed
+  audience: [operators]
+  scope: package
+  targets: ['@cleocode/core']
+  impact: Deterministic release notes get structured context.
+  includeInChangelog: true
+---
+`,
+    );
+
+    expect(parseChangesetFile(file)).toMatchObject({
+      releaseNotes: {
+        section: 'changed',
+        audience: ['operators'],
+        scope: 'package',
+        targets: ['@cleocode/core'],
+        impact: 'Deterministic release notes get structured context.',
+        includeInChangelog: true,
+      },
+    });
+  });
+
+  it('fails malformed release-note metadata with file and line context', async () => {
+    const parseChangesetFile = await loadParseChangesetFile();
+    const file = writeChangeset(
+      't10480-bad-metadata.md',
+      `---
+id: t10480-bad-metadata
+tasks: [T10480]
+kind: feat
+summary: Bad release-note metadata.
+releaseNotes:
+  section: feature
+---
+`,
+    );
+
+    expect(() => parseChangesetFile(file)).toThrow(
+      new RegExp(`${file.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}:7[\\s\\S]*releaseNotes\\.section`),
+    );
+  });
+});

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

@@ -19,6 +19,7 @@ import {
   EvidenceAtomSchema,
   EvidenceParseError,
   formatGateRequirement,
+  formatGateRequirementHint,
   GATE_EVIDENCE_REQUIREMENTS,
   parseEvidenceString,
   validateEvidenceForGate,
@@ -497,3 +498,90 @@ describe('formatGateRequirement (T10337)', () => {
     expect(formatGateRequirement('cleanupDone')).toBe('[note]');
   });
 });
+
+// ─── formatGateRequirementHint — rich CLI `fix:` surface (T9949) ────────────
+
+describe('formatGateRequirementHint (T9949)', () => {
+  it('renders implemented as multi-line list of copy-pasteable verify commands', () => {
+    const h = formatGateRequirementHint('implemented');
+    // Header line names the gate and uses "ONE of" framing.
+    expect(h).toMatch(/^Gate 'implemented' requires programmatic evidence\. Use ONE of:/);
+    // Each combination renders as a complete `cleo verify ... --evidence '<atoms>'` line.
+    expect(h).toContain("--evidence 'commit:<sha>;files:path/a.ts,path/b.ts'");
+    expect(h).toContain("--evidence 'commit:<sha>;note:<short description>'");
+    expect(h).toContain("--evidence 'decision:D-arch-001;files:path/a.ts,path/b.ts'");
+    expect(h).toContain("--evidence 'decision:D-arch-001;note:<short description>'");
+    expect(h).toContain("--evidence 'pr:357'");
+    // Routes a `note:`-only caller at the partner atom they need.
+    expect(h).toContain("'note:' alone is NOT accepted for this gate");
+    expect(h).toContain("'commit:'");
+    expect(h).toContain("'decision:'");
+  });
+
+  it('routes note-only callers for testsPassed at the right alternatives', () => {
+    // testsPassed accepts test-run, tool, or pr — none of which involve note.
+    const h = formatGateRequirementHint('testsPassed');
+    expect(h).toContain("--evidence 'test-run:/tmp/vitest-out.json'");
+    expect(h).toContain("--evidence 'tool:test'");
+    expect(h).toContain("--evidence 'pr:357'");
+    // When no combination includes note at all, the helper falls through to a
+    // generic "not accepted, see ADR-051" clarifier rather than fabricating a
+    // partner suggestion.
+    expect(h).toContain("'note:' is NOT accepted for this gate");
+    expect(h).toContain('ADR-051');
+  });
+
+  it('confirms note-only acceptance for cleanupDone', () => {
+    const h = formatGateRequirementHint('cleanupDone');
+    expect(h).toContain("--evidence 'note:<short description>'");
+    expect(h).toContain("'note:' alone IS accepted for this gate");
+  });
+
+  it('confirms note-only acceptance for securityPassed and nexusImpact', () => {
+    for (const gate of ['securityPassed', 'nexusImpact'] as const) {
+      const h = formatGateRequirementHint(gate);
+      expect(h, `${gate}: should confirm note alone is accepted`).toContain(
+        "'note:' alone IS accepted for this gate",
+      );
+    }
+  });
+
+  it('renders documented with files and url, and points away from note', () => {
+    const h = formatGateRequirementHint('documented');
+    expect(h).toContain("--evidence 'files:path/a.ts,path/b.ts'");
+    expect(h).toContain("--evidence 'url:https://example.com/docs'");
+    // documented has no note pairings — generic clarifier path.
+    expect(h).toContain("'note:' is NOT accepted for this gate");
+  });
+});
+
+// ─── validateEvidenceForGate — failure carries `hint` (T9949) ───────────────
+
+describe('validateEvidenceForGate failure surface (T9949)', () => {
+  it('populates a `hint` field alongside the legacy `message`', () => {
+    const r = validateEvidenceForGate('implemented', [
+      { kind: 'note', note: 'just a note' },
+    ] as EvidenceAtomInput[]);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      // Legacy single-line message preserved byte-for-byte.
+      expect(r.message).toBe(
+        "Gate 'implemented' requires evidence: [commit AND files] OR [commit AND note] OR [decision AND files] OR [decision AND note] OR [pr]",
+      );
+      // New rich hint includes the same content as formatGateRequirementHint.
+      expect(r.hint).toBe(formatGateRequirementHint('implemented'));
+    }
+  });
+
+  it('notes-only against testsPassed surfaces the right alternatives', () => {
+    const r = validateEvidenceForGate('testsPassed', [
+      { kind: 'note', note: 'I ran the tests by hand' },
+    ] as EvidenceAtomInput[]);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.hint).toContain("--evidence 'tool:test'");
+      expect(r.hint).toContain("--evidence 'pr:357'");
+      expect(r.hint).toContain("'note:' is NOT accepted for this gate");
+    }
+  });
+});

package/src/changesets.ts

@@ -67,6 +67,91 @@ export const CHANGESET_KINDS = [
 /** Allowed values of {@link ChangesetEntry.kind}. */
 export type ChangesetKind = (typeof CHANGESET_KINDS)[number];
 
+// ─── Release-note metadata ───────────────────────────────────────────────────
+
+/**
+ * Deterministic release-note section override used by zero-token renderers.
+ *
+ * These values intentionally mirror Keep-a-Changelog style headings so release
+ * tooling can render higher-quality notes without an LLM/API/token dependency.
+ */
+export const CHANGESET_RELEASE_NOTE_SECTIONS = [
+  'added',
+  'changed',
+  'fixed',
+  'deprecated',
+  'removed',
+  'security',
+  'breaking',
+] as const;
+
+/** Allowed values of {@link ChangesetReleaseNotesMetadata.section}. */
+export type ChangesetReleaseNoteSection = (typeof CHANGESET_RELEASE_NOTE_SECTIONS)[number];
+
+/** Audience labels for deterministic release-note routing. */
+export const CHANGESET_RELEASE_NOTE_AUDIENCES = [
+  'users',
+  'operators',
+  'developers',
+  'maintainers',
+] as const;
+
+/** Allowed values of {@link ChangesetReleaseNotesMetadata.audience}. */
+export type ChangesetReleaseNoteAudience = (typeof CHANGESET_RELEASE_NOTE_AUDIENCES)[number];
+
+/** Scope labels for deterministic release-note routing. */
+export const CHANGESET_RELEASE_NOTE_SCOPES = [
+  'project',
+  'package',
+  'component',
+  'docs',
+  'ops',
+  'security',
+] as const;
+
+/** Allowed values of {@link ChangesetReleaseNotesMetadata.scope}. */
+export type ChangesetReleaseNoteScope = (typeof CHANGESET_RELEASE_NOTE_SCOPES)[number];
+
+const nonEmptyReleaseNoteText = z.string().min(1, 'release-note metadata text must be non-empty');
+const nonEmptyReleaseNoteList = z
+  .array(nonEmptyReleaseNoteText)
+  .min(1, 'release-note metadata list must contain at least one item');
+
+/**
+ * Optional deterministic metadata for release-note rendering.
+ *
+ * This is deliberately small, explicit, and strict: it gives release tooling
+ * structured author-provided facts (section, audience, target, impact, etc.)
+ * while preserving zero-token defaults and failing loudly on misspelled fields.
+ */
+export const ChangesetReleaseNotesMetadataSchema = z
+  .object({
+    /** Keep-a-Changelog style section/category override. */
+    section: z.enum(CHANGESET_RELEASE_NOTE_SECTIONS).optional(),
+    /** Intended readers for the note. */
+    audience: z.array(z.enum(CHANGESET_RELEASE_NOTE_AUDIENCES)).min(1).optional(),
+    /** Release-note scope. */
+    scope: z.enum(CHANGESET_RELEASE_NOTE_SCOPES).optional(),
+    /** Package/project/component targets affected by this entry. */
+    targets: nonEmptyReleaseNoteList.optional(),
+    /** User- or operator-visible impact statement. */
+    impact: nonEmptyReleaseNoteText.optional(),
+    /** Deterministic migration/action text, separate from breaking changes. */
+    migration: nonEmptyReleaseNoteText.optional(),
+    /** Deprecation detail for Deprecated sections. */
+    deprecation: nonEmptyReleaseNoteText.optional(),
+    /** Security detail for Security sections. */
+    security: nonEmptyReleaseNoteText.optional(),
+    /** Operator-facing rollout/verification note. */
+    operatorNotes: nonEmptyReleaseNoteText.optional(),
+    /** Explicit inclusion toggle for future release-scope filters. */
+    includeInChangelog: z.boolean().optional(),
+  })
+  .strict();
+
+/** Inferred TypeScript type for deterministic release-note metadata. */
+export type ChangesetReleaseNotesMetadata = z.infer<typeof ChangesetReleaseNotesMetadataSchema>;
+
 // ─── Task ID validator ────────────────────────────────────────────────────────
 
 /**
@@ -93,14 +178,18 @@ const TASK_ID_RE = /^(T\d+(-[A-Z][A-Za-z0-9]*)?|E-\d+(-[A-Z][A-Za-z0-9]*)?)$/;
  * - `prs`      — linked PR numbers
  * - `notes`    — longer-form markdown body
  * - `breaking` — required migration note when `kind === 'breaking'`
+ * - `releaseNotes` — deterministic zero-token release-note metadata
  */
 export const ChangesetEntrySchema = z
   .object({
-    /** Filename slug (without the `.md` extension). */
+    /** Filename identifier (without the `.md` extension); lowercase kebab-case for new files, legacy uppercase task IDs accepted. */
     id: z
       .string()
       .min(1, 'id must be non-empty')
-      .regex(/^[a-z0-9][a-z0-9-]*$/, 'id must be kebab-case (lowercase, digits, hyphens)'),
+      .regex(
+        /^[A-Za-z0-9][A-Za-z0-9-]*$/,
+        'id must contain only ASCII letters, digits, and hyphens',
+      ),
     /** One or more CLEO task IDs this change is anchored to. */
     tasks: z
       .array(z.string().regex(TASK_ID_RE, 'task ID must match T#### or E-#### format'))
@@ -115,6 +204,8 @@ export const ChangesetEntrySchema = z
     notes: z.string().optional(),
     /** Migration note. Required iff `kind === 'breaking'`. */
     breaking: z.string().optional(),
+    /** Structured author-provided metadata for deterministic release notes. */
+    releaseNotes: ChangesetReleaseNotesMetadataSchema.optional(),
   })
   .refine((entry) => entry.kind !== 'breaking' || (entry.breaking?.length ?? 0) > 0, {
     message: 'breaking entries must include a non-empty `breaking` migration note',

package/src/dispatch/operations-registry.ts

@@ -7629,6 +7629,37 @@ export const OPERATIONS: OperationDef[] = [
     ] 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
+  // gateway because no DB or filesystem mutation occurs.
+  {
+    gateway: 'query',
+    domain: 'release',
+    operation: 'validate-changelog',
+    description:
+      'release.validate-changelog (query) — validate that CHANGELOG.md contains the canonical `## [VERSION]` header per ADR-028 §2.5. Replaces the brittle inline grep in .github/workflows/release.yml (T9937 / Saga T9862).',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['version'],
+    params: [
+      {
+        name: 'version',
+        type: 'string',
+        required: true,
+        description: 'Release version (accepts v2026.5.94 or 2026.5.94)',
+        cli: { positional: true },
+      },
+      {
+        name: 'changelogPath',
+        type: 'string',
+        required: false,
+        description: 'Override the CHANGELOG file path (default: <projectRoot>/CHANGELOG.md)',
+      },
+    ] satisfies ParamDef[],
+  },
+
   // ---------------------------------------------------------------------------
   // Provenance domain — `cleo provenance` CLI surface (T9528 · Phase 2 of T9493)
   // ---------------------------------------------------------------------------

package/src/evidence-atom-schema.ts

@@ -332,14 +332,25 @@ export const GATE_EVIDENCE_REQUIREMENTS: Readonly<
  * 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.
+ * Failure carries:
+ *   - {@link EvidenceValidationFailure.message} — the legacy single-line
+ *     `Gate '<gate>' requires evidence: [<combo>] OR [<combo>]` format,
+ *     preserved byte-for-byte for backward-compat with surfaces and tests
+ *     that match against it.
+ *   - {@link EvidenceValidationFailure.hint} — a richer, multi-line,
+ *     example-bearing remediation hint suitable for CLI `fix:` surfaces.
+ *     Added by T9949 so `E_EVIDENCE_INSUFFICIENT` errors point clearly at
+ *     the alternative atom the caller needs (e.g. "this gate requires
+ *     real proof — note: alone is not accepted; use commit+files,
+ *     commit+note, or pr instead").
  */
-export type EvidenceValidationResult =
-  | { readonly ok: true }
-  | { readonly ok: false; readonly message: string };
+export interface EvidenceValidationFailure {
+  readonly ok: false;
+  readonly message: string;
+  readonly hint: string;
+}
+
+export type EvidenceValidationResult = { readonly ok: true } | EvidenceValidationFailure;
 
 /**
  * Format the satisfying-combinations spec for a gate as the legacy
@@ -354,6 +365,114 @@ export function formatGateRequirement(gate: VerificationGate): string {
   return requirement.oneOf.map((set) => `[${set.join(' AND ')}]`).join(' OR ');
 }
 
+/**
+ * Example `--evidence` strings for each atom kind. Used by
+ * {@link formatGateRequirementHint} to render copy-pasteable remediation
+ * commands in CLI error surfaces.
+ *
+ * @task T9949
+ */
+const ATOM_EXAMPLES: Readonly<Record<EvidenceAtomKind, string>> = Object.freeze({
+  commit: 'commit:<sha>',
+  files: 'files:path/a.ts,path/b.ts',
+  'test-run': 'test-run:/tmp/vitest-out.json',
+  tool: 'tool:test',
+  url: 'url:https://example.com/docs',
+  note: 'note:<short description>',
+  decision: 'decision:D-arch-001',
+  pr: 'pr:357',
+  'loc-drop': 'loc-drop:<fromLines>:<toLines>',
+  'callsite-coverage': 'callsite-coverage:<symbolName>:<relativeSourcePath>',
+});
+
+/**
+ * Render a satisfying atom combination as a copy-pasteable `--evidence`
+ * string fragment, e.g. `['commit', 'files']` → `commit:<sha>;files:path/a.ts,path/b.ts`.
+ *
+ * @internal
+ */
+function renderCombinationAsEvidence(combination: ReadonlyArray<EvidenceAtomKind>): string {
+  return combination.map((kind) => ATOM_EXAMPLES[kind]).join(';');
+}
+
+/**
+ * Produce a multi-line, example-bearing remediation hint for a gate.
+ *
+ * Designed for CLI `fix:` surfaces so `E_EVIDENCE_INSUFFICIENT` errors point
+ * the caller at the specific alternative atom shape they need. The hint lists
+ * every satisfying combination as a copy-pasteable `cleo verify` invocation
+ * plus a note-specific clarification when the gate does NOT accept `note:`
+ * alone.
+ *
+ * The motivating bug (T9949) was that note-only deliverables (decision-only
+ * tasks, deletion-only refactors) hit `E_EVIDENCE_INSUFFICIENT` with the
+ * legacy single-line error and had to consult ADR-051 to figure out which
+ * additional atom kind the gate required. The richer hint inlines the answer.
+ *
+ * @param gate - Verification gate the hint is for.
+ * @returns Multi-line remediation hint suitable for an `engineError({fix:})`
+ *   surface. Always ends in a clarifying sentence about whether `note:` alone
+ *   is accepted for the gate.
+ *
+ * @example
+ * ```ts
+ * formatGateRequirementHint('implemented');
+ * // "Gate 'implemented' requires programmatic evidence. Use ONE of:
+ * //   - cleo verify T#### --gate implemented --evidence 'commit:<sha>;files:path/a.ts,path/b.ts'
+ * //   - cleo verify T#### --gate implemented --evidence 'commit:<sha>;note:<short description>'
+ * //   - cleo verify T#### --gate implemented --evidence 'decision:D-arch-001;files:path/a.ts,path/b.ts'
+ * //   - cleo verify T#### --gate implemented --evidence 'decision:D-arch-001;note:<short description>'
+ * //   - cleo verify T#### --gate implemented --evidence 'pr:357'
+ * // Note: 'note:' alone is NOT accepted for this gate — pair it with 'commit:' or 'decision:'."
+ * ```
+ *
+ * @task T9949
+ * @adr ADR-051 §2.3
+ */
+export function formatGateRequirementHint(gate: VerificationGate): string {
+  const requirement = GATE_EVIDENCE_REQUIREMENTS[gate];
+  if (!requirement) {
+    // Unknown gate — match validateEvidenceForGate's defensive default.
+    return `Gate '${gate}' has no documented evidence requirements.`;
+  }
+
+  const lines: string[] = [
+    `Gate '${gate}' requires programmatic evidence. Use ONE of:`,
+    ...requirement.oneOf.map(
+      (combo) =>
+        `  - cleo verify T#### --gate ${gate} --evidence '${renderCombinationAsEvidence(combo)}'`,
+    ),
+  ];
+
+  // Note-specific clarification — T9949's headline pain point.
+  // The gate accepts note: alone IFF some single-element combination is ['note'].
+  const noteAloneAccepted = requirement.oneOf.some(
+    (combo) => combo.length === 1 && combo[0] === 'note',
+  );
+  if (noteAloneAccepted) {
+    lines.push(`Note: 'note:' alone IS accepted for this gate (waiver-style evidence).`);
+  } else {
+    // Surface every alternative pairing involving note for at-a-glance routing.
+    const notePairings = requirement.oneOf.filter(
+      (combo) => combo.length > 1 && combo.includes('note'),
+    );
+    if (notePairings.length > 0) {
+      const partners = Array.from(
+        new Set(notePairings.flatMap((combo) => combo.filter((k) => k !== 'note'))),
+      ).map((k) => `'${k}:'`);
+      lines.push(
+        `Note: 'note:' alone is NOT accepted for this gate — pair it with ${partners.join(' or ')}.`,
+      );
+    } else {
+      lines.push(
+        `Note: 'note:' is NOT accepted for this gate (even when paired). See ADR-051 for the full grammar.`,
+      );
+    }
+  }
+
+  return lines.join('\n');
+}
+
 /**
  * Check whether a set of parsed atoms satisfies the requirement spec for
  * `gate`.
@@ -401,6 +520,11 @@ export function validateEvidenceForGate(
   return {
     ok: false,
     message: `Gate '${gate}' requires evidence: ${formatGateRequirement(gate)}`,
+    // T9949: rich, example-bearing remediation hint suitable for CLI `fix:`.
+    // Always populated alongside `message` so consumers can choose between
+    // the legacy single-line surface and the multi-line hint without re-
+    // computing the spec.
+    hint: formatGateRequirementHint(gate),
   };
 }
 

package/src/index.ts

@@ -475,6 +475,7 @@ export {
 export type {
   EvidenceAtom as EvidenceAtomInput,
   EvidenceAtomKind,
+  EvidenceValidationFailure,
   EvidenceValidationResult,
   GateEvidenceRequirement,
 } from './evidence-atom-schema.js';
@@ -486,6 +487,7 @@ export {
   EvidenceParseError,
   filesAtomSchema,
   formatGateRequirement,
+  formatGateRequirementHint,
   GATE_EVIDENCE_REQUIREMENTS,
   locDropAtomSchema,
   noteAtomSchema,

package/src/operations/tasks.ts

@@ -138,6 +138,32 @@ export interface TasksFindParams {
    * @task T9905
    */
   urgent?: boolean;
+  /**
+   * Filter by label — selects tasks whose `labels` array contains this
+   * value. Composes with other filters via AND.
+   *
+   * Closes GH#393 — gives `cleo find --label <name>` parity with the
+   * positional `cleo labels <name>` surface.
+   *
+   * @task T9904
+   */
+  label?: string;
+  /**
+   * Filter by parent task ID — restricts the result set to tasks whose
+   * `parentId` equals this value. Mirrors the `--parent` axis on
+   * `cleo list`. When the parent task is a Saga (Epic with
+   * `label='saga'`), routing goes through `task_relations.type='groups'`
+   * member IDs instead of the `parentId` column (ADR-073 §1).
+   *
+   * Composes with other filters via AND. Closes T10108 — pre-fix,
+   * `cleo find "" --parent <id>` returned every task in the project
+   * because the empty-string query bypassed all filters via
+   * `fuzzyScore('', '<title>')===80`.
+   *
+   * @task T10108
+   * @saga T9862
+   */
+  parent?: string;
 }
 export type TasksFindResult = MinimalTask[];