@cleocode/contracts 2026.5.114 → 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/__tests__/meta-tokens.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Type-shape contract test for the envelope-wide `meta.tokens` field
+ * promoted in T9923 (Saga T9855 / E8.4).
+ *
+ * `CliMeta.tokens` is the first-class structured token-cost annotation
+ * attached to every CLI envelope (formerly the underscore-prefixed
+ * `meta._tokenEstimate`). The legacy field is retained for ONE release
+ * (removeAt v2026.7.0) so existing consumers can migrate without a
+ * flag-day.
+ *
+ * @epic T9919
+ * @task T9923
+ * @saga T9855
+ */
+
+import type { CliEnvelope, CliMeta, CliMetaTokens } from '@cleocode/lafs';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+describe('CliMeta.tokens type shape (T9923)', () => {
+  it('accepts the full first-class CliMetaTokens shape', () => {
+    const meta: CliMeta = {
+      operation: 'tasks.show',
+      requestId: '00000000-0000-0000-0000-000000000000',
+      duration_ms: 0,
+      timestamp: '2026-05-24T00:00:00.000Z',
+      tokens: {
+        estimate: 1234,
+        model: 'cl100k',
+        calculatedAt: '2026-05-24T00:00:00.000Z',
+      },
+    };
+    expect(meta.tokens?.estimate).toBe(1234);
+    expect(meta.tokens?.model).toBe('cl100k');
+    expect(meta.tokens?.calculatedAt).toBe('2026-05-24T00:00:00.000Z');
+  });
+
+  it('requires `estimate` to be a number when `tokens` is present', () => {
+    expectTypeOf<NonNullable<CliMeta['tokens']>['estimate']>().toEqualTypeOf<number>();
+    expectTypeOf<NonNullable<CliMeta['tokens']>['model']>().toEqualTypeOf<string>();
+    expectTypeOf<NonNullable<CliMeta['tokens']>['calculatedAt']>().toEqualTypeOf<string>();
+  });
+
+  it('is optional — omitting `tokens` leaves a valid CliMeta', () => {
+    const meta: CliMeta = {
+      operation: 'tasks.list',
+      requestId: '00000000-0000-0000-0000-000000000001',
+      duration_ms: 0,
+      timestamp: '2026-05-24T00:00:00.000Z',
+    };
+    expect(meta.tokens).toBeUndefined();
+  });
+
+  it('accepts the legacy `_tokenEstimate` field during the deprecation window', () => {
+    const meta: CliMeta = {
+      operation: 'tasks.show',
+      requestId: '00000000-0000-0000-0000-000000000002',
+      duration_ms: 0,
+      timestamp: '2026-05-24T00:00:00.000Z',
+      _tokenEstimate: { estimate: 999 },
+    };
+    expect(meta._tokenEstimate?.estimate).toBe(999);
+  });
+
+  it('allows BOTH `tokens` and `_tokenEstimate` for backwards-compat dual-write', () => {
+    const meta: CliMeta = {
+      operation: 'tasks.show',
+      requestId: '00000000-0000-0000-0000-000000000003',
+      duration_ms: 0,
+      timestamp: '2026-05-24T00:00:00.000Z',
+      tokens: {
+        estimate: 4321,
+        model: 'o200k',
+        calculatedAt: '2026-05-24T00:00:00.000Z',
+      },
+      _tokenEstimate: { estimate: 4321 },
+    };
+    expect(meta.tokens?.estimate).toBe(meta._tokenEstimate?.estimate);
+  });
+
+  it('flows through CliEnvelope<T>.meta verbatim', () => {
+    const envelope: CliEnvelope<{ taskId: string }> = {
+      success: true,
+      data: { taskId: 'T9923' },
+      meta: {
+        operation: 'tasks.show',
+        requestId: '00000000-0000-0000-0000-000000000004',
+        duration_ms: 1,
+        timestamp: '2026-05-24T00:00:00.000Z',
+        tokens: {
+          estimate: 512,
+          model: 'cl100k',
+          calculatedAt: '2026-05-24T00:00:00.000Z',
+        },
+      },
+    };
+    expect(envelope.meta.tokens?.estimate).toBe(512);
+  });
+
+  it('CliMetaTokens is structurally compatible with manual construction', () => {
+    const t: CliMetaTokens = {
+      estimate: 100,
+      model: 'approx',
+      calculatedAt: '2026-05-24T00:00:00.000Z',
+    };
+    expect(t.estimate).toBe(100);
+  });
+});

package/src/boundary.ts

@@ -492,7 +492,7 @@ export const BOUNDARY_REGISTRY: readonly BoundaryEntry[] = [
       panic_unwind: 'allowed-with-recovery',
       root_escape: 'forbidden',
     },
-    amendments: ['adr-077-worktreeinclude'],
+    amendments: ['adr-087-worktree-ffi-topology'],
     rationale:
       'napi binding shim (515 LOC) for worktrunk-core, used by packages/core spawn-pipeline tests, packages/core/src/scaffold/ensure-config.ts, and shipped via packages/worktree-napi-* per-platform npm packages. Internal-only.',
   },
@@ -510,7 +510,7 @@ export const BOUNDARY_REGISTRY: readonly BoundaryEntry[] = [
       panic_unwind: 'forbidden',
       root_escape: 'forbidden',
     },
-    amendments: ['adr-077-worktreeinclude', 'adr-078-boundary-registry'],
+    amendments: ['adr-077-worktreeinclude-canonical-location', 'adr-078-boundary-registry'],
     rationale:
       'Refactored SoC per ADR-078 amendment 2026-05-23. Worktree primitives core (1,352 LOC) vendored from /mnt/projects/worktrunk per D010, consumed by worktree-napi. Reference implementation of the boundary-registry pattern. Full SDK surface documented in crates/worktrunk-core/README.md (T10223). Internal-only today; publish=true is a future option if external worktree-tooling emerges.',
   },
@@ -868,7 +868,7 @@ export const BOUNDARY_REGISTRY: readonly BoundaryEntry[] = [
       root_escape: 'forbidden',
       fs_writes_outside_root: 'audited',
     },
-    amendments: ['adr-077-worktreeinclude', 'adr-078-boundary-registry'],
+    amendments: ['adr-087-worktree-ffi-topology', 'adr-078-boundary-registry'],
     rationale:
       'Worktree SSoT primitive layer (1,972 LOC) — canonical create/destroy/list/prune/include/copy-on-write bound by @cleocode/paths. Post-PR-#487 the responsibilities are distinct from packages/core/src/worktree/ (SDK-level enrichment). Consumes worktrunk-core via worktree-napi.',
   },

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',