@cleocode/contracts 2026.5.112 → 2026.5.113

package/dist/templates/manifest.js

@@ -0,0 +1,165 @@
+/**
+ * TemplateManifest contract — SSoT for every template CLEO ships, installs,
+ * or rewrites during `cleo init` / `cleo upgrade` / `cleo scaffold-*`.
+ *
+ * A {@link TemplateManifestEntry} declares one template file: where its
+ * source lives in the monorepo, where it installs into a consumer project,
+ * how its placeholders are substituted, which placeholders it accepts, and
+ * how it MUST be reconciled when the shipped version moves ahead of the
+ * deployed copy.
+ *
+ * This contract is the leaf type. The CORE-side template registry
+ * (T9877) consumes it; the CLI verbs (`cleo init --workflows`,
+ * `cleo upgrade`, the scaffold sweeper) read the manifest at runtime to
+ * decide what to write, what to skip, and what to diff-prompt the user on.
+ *
+ * @example minimal workflow template entry
+ * ```ts
+ * import { TemplateManifestEntrySchema, type TemplateManifestEntry } from '@cleocode/contracts';
+ *
+ * const entry: TemplateManifestEntry = TemplateManifestEntrySchema.parse({
+ *   id: 'ci.yml',
+ *   kind: 'workflow',
+ *   sourcePath: 'packages/core/templates/workflows/ci.yml.tmpl',
+ *   installPath: '.github/workflows/ci.yml',
+ *   substitution: 'regex-tmpl',
+ *   placeholders: [
+ *     {
+ *       name: 'NODE_VERSION',
+ *       source: 'project-context',
+ *       sourcePath: 'engines.node',
+ *       defaultValue: 24,
+ *     },
+ *   ],
+ *   updateStrategy: 'overwrite-on-bump',
+ * });
+ * ```
+ *
+ * @task T9875
+ * @epic T9874
+ * @saga T9855
+ * @see ADR-076 (canonical doc routing — same boundary discipline applies here)
+ */
+import { z } from 'zod';
+// ─── TemplateKind ─────────────────────────────────────────────────────────────
+/**
+ * Allowed categories of template the manifest can describe.
+ *
+ * - `workflow`  — GitHub Actions / CI workflow files.
+ * - `config`    — Configuration files (e.g. `.editorconfig`, `tsconfig.json`).
+ * - `agent`     — Agent definition files shipped to `.claude/agents/` etc.
+ * - `skill`     — Skill markdown shipped to `.claude/skills/` etc.
+ * - `provider`  — Provider-specific bootstrap files (Anthropic, OpenAI, …).
+ * - `doc`       — Documentation scaffolds (e.g. README.md, AGENTS.md).
+ */
+export const TEMPLATE_KINDS = ['workflow', 'config', 'agent', 'skill', 'provider', 'doc'];
+// ─── TemplateSubstitution ─────────────────────────────────────────────────────
+/**
+ * Allowed substitution strategies a template can request.
+ *
+ * - `regex-tmpl` — `{{KEY}}` placeholder substitution via regex.
+ * - `static`     — No substitution; the file is copied byte-for-byte.
+ * - `json-merge` — The template is parsed as JSON and merged into any
+ *                  existing JSON file at `installPath`; placeholders inside
+ *                  string values still go through `regex-tmpl`.
+ */
+export const TEMPLATE_SUBSTITUTIONS = ['regex-tmpl', 'static', 'json-merge'];
+// ─── UpdateStrategy ───────────────────────────────────────────────────────────
+/**
+ * How an installed template is reconciled with the shipped copy on
+ * `cleo upgrade` / `cleo init --force`.
+ *
+ * - `overwrite-on-bump` — Always overwrite when the manifest version is
+ *                        newer than the deployed copy.
+ * - `diff-prompt`       — Show a diff and ask the user before overwriting.
+ * - `immutable`         — Never overwrite once installed.
+ * - `manifest-merge`    — Apply structural merge (e.g. JSON deep-merge,
+ *                        respecting existing user keys).
+ */
+export const TEMPLATE_UPDATE_STRATEGIES = [
+    'overwrite-on-bump',
+    'diff-prompt',
+    'immutable',
+    'manifest-merge',
+];
+// ─── PlaceholderSpec ──────────────────────────────────────────────────────────
+/**
+ * Allowed resolver sources a {@link PlaceholderSpec} can reference.
+ *
+ * - `project-context` — `.cleo/project-context.json` (detected ecosystem hints).
+ * - `project-info`    — `.cleo/project-info.json` (per-project metadata).
+ * - `.cleo/config`    — Per-project config (`<projectRoot>/.cleo/config.json`).
+ * - `~/.cleo/config`  — User-global config (`$XDG_CONFIG_HOME/cleo/config.json`).
+ * - `tool-resolver`   — Resolved via the per-language tool resolver
+ *                       (e.g. `pnpm` vs `npm` chosen by `primaryType`).
+ * - `literal`         — Hard-coded value baked into the manifest entry.
+ */
+export const PLACEHOLDER_SOURCES = [
+    'project-context',
+    'project-info',
+    '.cleo/config',
+    '~/.cleo/config',
+    'tool-resolver',
+    'literal',
+];
+/**
+ * Zod schema for a single placeholder declaration on a template entry.
+ *
+ * Each placeholder is resolved at install time by reading `sourcePath` from
+ * the named `source`. If resolution returns `undefined`, the installer
+ * falls back to `defaultValue`; if neither yields a value, installation
+ * fails with `E_PLACEHOLDER_UNRESOLVED`.
+ */
+export const PlaceholderSpecSchema = z.object({
+    /**
+     * Placeholder identifier as it appears in the template body
+     * (e.g. `NODE_VERSION` matches `{{NODE_VERSION}}`).
+     */
+    name: z.string().min(1, 'placeholder name must be non-empty'),
+    /** Resolver source the installer consults for this placeholder. */
+    source: z.enum(PLACEHOLDER_SOURCES),
+    /**
+     * Path expression evaluated against `source` (e.g. `engines.node` against
+     * `project-context`, `defaults.branchModel` against `.cleo/config`).
+     * For `literal` source, this MAY be the literal value's identifier.
+     */
+    sourcePath: z.string().min(1, 'placeholder sourcePath must be non-empty'),
+    /**
+     * Fallback value used when `source[sourcePath]` resolves to `undefined`.
+     * `null` is permitted to explicitly mark "no default — failure required".
+     */
+    defaultValue: z.union([z.string(), z.number(), z.boolean(), z.null()]).optional(),
+});
+// ─── TemplateManifestEntry ────────────────────────────────────────────────────
+/**
+ * Zod schema for a single template manifest entry.
+ *
+ * Validates the full descriptor a template registry consumer needs to
+ * install a template file:
+ *
+ * - `id`             — Stable identifier (kebab-case, matches install basename
+ *                      or a domain-unique slug).
+ * - `kind`           — One of {@link TEMPLATE_KINDS}.
+ * - `sourcePath`     — Repo-relative path of the template source.
+ * - `installPath`    — Project-relative path where the rendered file lands.
+ * - `substitution`   — One of {@link TEMPLATE_SUBSTITUTIONS}.
+ * - `placeholders`   — Declared placeholders the installer must resolve.
+ * - `updateStrategy` — Reconciliation policy on upgrade.
+ */
+export const TemplateManifestEntrySchema = z.object({
+    /** Stable identifier for this template entry. */
+    id: z.string().min(1, 'id must be non-empty'),
+    /** Category of file this template represents. */
+    kind: z.enum(TEMPLATE_KINDS),
+    /** Repo-relative path of the template source file. */
+    sourcePath: z.string().min(1, 'sourcePath must be non-empty'),
+    /** Project-relative path where the rendered template installs. */
+    installPath: z.string().min(1, 'installPath must be non-empty'),
+    /** Substitution strategy the installer applies to `sourcePath`. */
+    substitution: z.enum(TEMPLATE_SUBSTITUTIONS),
+    /** Declared placeholders this template requires. May be empty. */
+    placeholders: z.array(PlaceholderSpecSchema),
+    /** Reconciliation policy on upgrade. */
+    updateStrategy: z.enum(TEMPLATE_UPDATE_STRATEGIES),
+});
+//# sourceMappingURL=manifest.js.map

package/dist/templates/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/templates/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,iFAAiF;AAEjF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,CAAU,CAAC;AAKnG,iFAAiF;AAEjF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,YAAY,EAAE,QAAQ,EAAE,YAAY,CAAU,CAAC;AAKtF,iFAAiF;AAEjF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,mBAAmB;IACnB,aAAa;IACb,WAAW;IACX,gBAAgB;CACR,CAAC;AAKX,iFAAiF;AAEjF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,iBAAiB;IACjB,cAAc;IACd,cAAc;IACd,gBAAgB;IAChB,eAAe;IACf,SAAS;CACD,CAAC;AAKX;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C;;;OAGG;IACH,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,oCAAoC,CAAC;IAC7D,mEAAmE;IACnE,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC;IACnC;;;;OAIG;IACH,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,0CAA0C,CAAC;IACzE;;;OAGG;IACH,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE;CAClF,CAAC,CAAC;AAYH,iFAAiF;AAEjF;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,iDAAiD;IACjD,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,sBAAsB,CAAC;IAC7C,iDAAiD;IACjD,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC;IAC5B,sDAAsD;IACtD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,8BAA8B,CAAC;IAC7D,kEAAkE;IAClE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,+BAA+B,CAAC;IAC/D,mEAAmE;IACnE,YAAY,EAAE,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC;IAC5C,kEAAkE;IAClE,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,qBAAqB,CAAC;IAC5C,wCAAwC;IACxC,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC;CACnD,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.5.112",
+  "version": "2026.5.113",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",
@@ -138,7 +138,7 @@
   "dependencies": {
     "zod": "^4.3.6",
     "zod-to-json-schema": "^3.25.2",
-    "@cleocode/lafs": "2026.5.112"
+    "@cleocode/lafs": "2026.5.113"
   },
   "scripts": {
     "build": "tsc -b --force && node scripts/copy-assets.mjs && node scripts/emit-schemas.mjs",

package/src/__tests__/cli-meta-suggested-next.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Type-shape contract test for the envelope-wide `meta.suggestedNext`
+ * field promoted in T9920 (Saga T9855 / E8.1).
+ *
+ * `CliMeta.suggestedNext` is the canonical LLM-next-action hint
+ * surfaced on every CLI envelope. This test asserts the type allows
+ * the optional `ReadonlyArray<string>` shape and never widens to
+ * `string | null` or to nested objects (which would re-introduce the
+ * pre-T9920 nexus-internal-only structured form at the envelope tier).
+ *
+ * The runtime `attachSuggestedNext` helper lives in
+ * `packages/core/src/dispatch/suggested-next.ts` and is exercised by
+ * `packages/core/src/dispatch/__tests__/suggested-next.test.ts` —
+ * contracts cannot import core without breaking the layering contract.
+ *
+ * @epic T9919
+ * @task T9920
+ * @saga T9855
+ */
+
+import type { CliEnvelope, CliMeta } from '@cleocode/lafs';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+describe('CliMeta.suggestedNext type shape (T9920)', () => {
+  it('allows ReadonlyArray<string>', () => {
+    const meta: CliMeta = {
+      operation: 'tasks.show',
+      requestId: '00000000-0000-0000-0000-000000000000',
+      duration_ms: 0,
+      timestamp: '2026-05-24T00:00:00.000Z',
+      suggestedNext: ['cleo focus T1234', 'cleo verify T1234'],
+    };
+    expect(meta.suggestedNext).toEqual(['cleo focus T1234', 'cleo verify T1234']);
+  });
+
+  it('is optional — omitting it 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.suggestedNext).toBeUndefined();
+  });
+
+  it('accepts an empty array (explicit "no follow-up suggested")', () => {
+    const meta: CliMeta = {
+      operation: 'tasks.show',
+      requestId: '00000000-0000-0000-0000-000000000002',
+      duration_ms: 0,
+      timestamp: '2026-05-24T00:00:00.000Z',
+      suggestedNext: [],
+    };
+    expect(meta.suggestedNext).toEqual([]);
+    expect(Array.isArray(meta.suggestedNext)).toBe(true);
+  });
+
+  it('typechecks as ReadonlyArray<string> — never `null`, never nested objects', () => {
+    expectTypeOf<CliMeta['suggestedNext']>().toEqualTypeOf<ReadonlyArray<string> | undefined>();
+  });
+
+  it('flows through CliEnvelope<T>.meta verbatim', () => {
+    const envelope: CliEnvelope<{ taskId: string }> = {
+      success: true,
+      data: { taskId: 'T1234' },
+      meta: {
+        operation: 'tasks.show',
+        requestId: '00000000-0000-0000-0000-000000000003',
+        duration_ms: 1,
+        timestamp: '2026-05-24T00:00:00.000Z',
+        suggestedNext: ['cleo focus T1234'],
+      },
+    };
+    expect(envelope.meta.suggestedNext).toEqual(['cleo focus T1234']);
+  });
+});

package/src/config/__tests__/manifest.test.ts

@@ -0,0 +1,176 @@
+/**
+ * Tests for the ConfigManifest contract (T9876 / Saga T9855 / ADR-076).
+ *
+ * Covers:
+ * - Schema round-trip for each of the 4 built-in entries.
+ * - Merge-precedence invariant (project > global > defaults).
+ * - Metadata-scope isolation (NOT in the merge chain).
+ * - {@link DriftDetection} exhaustiveness via a `never` fallback switch.
+ *
+ * @task T9876
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  CLEO_CONFIG_MANIFEST,
+  CONFIG_MANIFEST_ENTRIES,
+  type ConfigManifestEntry,
+  type ConfigScope,
+  configManifestEntrySchema,
+  type DriftDetection,
+  GLOBAL_CLEO_CONFIG_MANIFEST,
+  PROJECT_CONTEXT_MANIFEST,
+  PROJECT_INFO_MANIFEST,
+} from '../manifest.js';
+
+describe('ConfigManifest built-in entries', () => {
+  const builtins: ReadonlyArray<readonly [string, ConfigManifestEntry]> = [
+    ['PROJECT_INFO_MANIFEST', PROJECT_INFO_MANIFEST],
+    ['PROJECT_CONTEXT_MANIFEST', PROJECT_CONTEXT_MANIFEST],
+    ['CLEO_CONFIG_MANIFEST', CLEO_CONFIG_MANIFEST],
+    ['GLOBAL_CLEO_CONFIG_MANIFEST', GLOBAL_CLEO_CONFIG_MANIFEST],
+  ];
+
+  for (const [name, entry] of builtins) {
+    it(`${name} validates against configManifestEntrySchema`, () => {
+      const parsed = configManifestEntrySchema.parse(entry);
+      expect(parsed.id).toBe(entry.id);
+      expect(parsed.scope).toBe(entry.scope);
+      expect(parsed.path).toBe(entry.path);
+      expect(parsed.mergePrecedence).toBe(entry.mergePrecedence);
+      expect(parsed.driftDetection).toBe(entry.driftDetection);
+    });
+  }
+
+  it('CONFIG_MANIFEST_ENTRIES contains all 4 built-in entries', () => {
+    const ids = CONFIG_MANIFEST_ENTRIES.map((e) => e.id).sort();
+    expect(ids).toEqual([
+      'cleo-config-global',
+      'cleo-config-project',
+      'project-context',
+      'project-info',
+    ]);
+  });
+
+  it('CONFIG_MANIFEST_ENTRIES is frozen', () => {
+    expect(Object.isFrozen(CONFIG_MANIFEST_ENTRIES)).toBe(true);
+  });
+});
+
+describe('Merge-precedence invariant (project > global > defaults)', () => {
+  it('project precedence > global precedence (higher wins)', () => {
+    expect(CLEO_CONFIG_MANIFEST.mergePrecedence).toBeGreaterThan(
+      GLOBAL_CLEO_CONFIG_MANIFEST.mergePrecedence,
+    );
+  });
+
+  it('canonical precedence values: project=20, global=10, metadata=0', () => {
+    expect(CLEO_CONFIG_MANIFEST.mergePrecedence).toBe(20);
+    expect(GLOBAL_CLEO_CONFIG_MANIFEST.mergePrecedence).toBe(10);
+    expect(PROJECT_INFO_MANIFEST.mergePrecedence).toBe(0);
+    expect(PROJECT_CONTEXT_MANIFEST.mergePrecedence).toBe(0);
+  });
+
+  it('cascade-resolver sort order yields global then project (project wins)', () => {
+    const cascadeEntries = CONFIG_MANIFEST_ENTRIES.filter(
+      (e): e is ConfigManifestEntry & { scope: ConfigScope } =>
+        e.scope === 'global' || e.scope === 'project',
+    )
+      .slice() // copy before sort — array is frozen
+      .sort((a, b) => a.mergePrecedence - b.mergePrecedence);
+
+    expect(cascadeEntries.map((e) => e.scope)).toEqual(['global', 'project']);
+  });
+});
+
+describe('Metadata-scope isolation', () => {
+  it('metadata entries are NOT in the cascade merge chain', () => {
+    const cascadeScopes = CONFIG_MANIFEST_ENTRIES.filter((e) => e.scope !== 'metadata').map(
+      (e) => e.scope,
+    );
+    expect(cascadeScopes).toEqual(expect.arrayContaining(['global', 'project']));
+    expect(cascadeScopes).not.toContain('metadata');
+  });
+
+  it('all metadata entries have mergePrecedence 0 (separate channel)', () => {
+    const metadataEntries = CONFIG_MANIFEST_ENTRIES.filter((e) => e.scope === 'metadata');
+    expect(metadataEntries.length).toBeGreaterThan(0);
+    for (const e of metadataEntries) {
+      expect(e.mergePrecedence).toBe(0);
+    }
+  });
+});
+
+describe('DriftDetection exhaustiveness (type-level)', () => {
+  it('switch over DriftDetection covers all variants with never fallback', () => {
+    const describe_ = (d: DriftDetection): string => {
+      switch (d) {
+        case 'schema-validate':
+          return 'schema-validate';
+        case 'staleness-gate':
+          return 'staleness-gate';
+        case 'value-diff':
+          return 'value-diff';
+        case 'none':
+          return 'none';
+        default: {
+          // If a new variant is added without updating this switch, TS will
+          // refuse to assign it to `never` at compile time.
+          const _exhaustive: never = d;
+          return _exhaustive;
+        }
+      }
+    };
+
+    expect(describe_('schema-validate')).toBe('schema-validate');
+    expect(describe_('staleness-gate')).toBe('staleness-gate');
+    expect(describe_('value-diff')).toBe('value-diff');
+    expect(describe_('none')).toBe('none');
+  });
+});
+
+describe('configManifestEntrySchema rejects invalid input', () => {
+  it('rejects empty id', () => {
+    const result = configManifestEntrySchema.safeParse({
+      id: '',
+      scope: 'project',
+      path: '.cleo/config.json',
+      mergePrecedence: 20,
+      driftDetection: 'schema-validate',
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects unknown scope', () => {
+    const result = configManifestEntrySchema.safeParse({
+      id: 'x',
+      scope: 'workspace',
+      path: '.cleo/x.json',
+      mergePrecedence: 0,
+      driftDetection: 'none',
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects negative mergePrecedence', () => {
+    const result = configManifestEntrySchema.safeParse({
+      id: 'x',
+      scope: 'project',
+      path: '.cleo/x.json',
+      mergePrecedence: -1,
+      driftDetection: 'none',
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects unknown driftDetection variant', () => {
+    const result = configManifestEntrySchema.safeParse({
+      id: 'x',
+      scope: 'project',
+      path: '.cleo/x.json',
+      mergePrecedence: 0,
+      driftDetection: 'sha-compare',
+    });
+    expect(result.success).toBe(false);
+  });
+});

package/src/config/manifest.ts

@@ -0,0 +1,218 @@
+/**
+ * ConfigManifest contract — declarative registry of every config-like file CLEO
+ * reads, writes, or merges, with its scope, schema, merge precedence, and the
+ * drift-detection strategy applied to it.
+ *
+ * Foundation for the CORE SSoT config registry (T9878) and the `resolveCleoConfig`
+ * cascade resolver. Built-in entries cover the four canonical CLEO files:
+ *
+ * - `~/.cleo/config.json`          (`global`,   precedence 10)
+ * - `<project>/.cleo/config.json`  (`project`,  precedence 20)
+ * - `<project>/.cleo/project-info.json`    (`metadata`, separate channel)
+ * - `<project>/.cleo/project-context.json` (`metadata`, separate channel)
+ *
+ * Merge semantics: higher `mergePrecedence` wins. The `metadata` scope is
+ * intentionally OUTSIDE the project ↔ global merge chain — those files are
+ * read-only consumer state and must NEVER be merged into resolved CleoConfig.
+ *
+ * @task T9876
+ * @saga T9855
+ * @adr 076
+ */
+
+import { type ZodTypeAny, z } from 'zod';
+
+// ───────────────────────────────────────────────────────────────────────────
+// Scope + drift unions
+// ───────────────────────────────────────────────────────────────────────────
+
+/**
+ * Cascade-participating scopes for the project ↔ global merge chain.
+ *
+ * - `'global'`  — `~/.cleo/config.json`        (precedence 10)
+ * - `'project'` — `<project>/.cleo/config.json` (precedence 20, higher wins)
+ *
+ * Note: `'metadata'` is NOT part of this union — metadata-scoped files are
+ * read-only consumer state and live on a separate channel. See
+ * {@link ConfigManifestScope} for the full union including metadata.
+ *
+ * @task T9876
+ */
+export type ConfigScope = 'global' | 'project';
+
+/**
+ * Full scope union covering cascade scopes AND the read-only `metadata`
+ * channel used by `project-info.json` and `project-context.json`.
+ *
+ * Metadata-scoped entries are NEVER merged into the resolved CleoConfig —
+ * they are surfaced separately as consumer state and validated only for
+ * schema conformance / staleness.
+ *
+ * @task T9876
+ */
+export type ConfigManifestScope = ConfigScope | 'metadata';
+
+/**
+ * Drift-detection strategy applied to a manifest entry.
+ *
+ * - `'schema-validate'` — Re-parse the file's contents against {@link ConfigManifestEntry.schema}
+ *   on read. Any parse error is reported as drift.
+ * - `'staleness-gate'`  — Compare the file's `detectedAt` (or equivalent freshness key)
+ *   against a freshness threshold. Stale files are flagged but not rejected.
+ * - `'value-diff'`      — Diff the file's resolved values against the manifest's
+ *   `defaults` baseline and report changed keys. Useful for invariant tracking.
+ * - `'none'`            — No drift detection. Entry is informational-only.
+ *
+ * @task T9876
+ */
+export type DriftDetection = 'schema-validate' | 'staleness-gate' | 'value-diff' | 'none';
+
+// ───────────────────────────────────────────────────────────────────────────
+// Manifest entry shape
+// ───────────────────────────────────────────────────────────────────────────
+
+/**
+ * A single registry entry describing one config-like file CLEO is aware of.
+ *
+ * `mergePrecedence` orders entries within the SAME scope channel. Across
+ * channels, the cascade-resolver consumes entries with `scope` in
+ * {@link ConfigScope} (global/project) and merges by ascending precedence
+ * (higher wins). Metadata entries are surfaced separately.
+ *
+ * @task T9876
+ */
+export interface ConfigManifestEntry {
+  /** Stable identifier for the entry (e.g. `'cleo-config-project'`). */
+  id: string;
+  /** Where the file lives in the precedence hierarchy. */
+  scope: ConfigManifestScope;
+  /** Absolute or `~`-rooted path to the file on disk. */
+  path: string;
+  /**
+   * Optional Zod schema used by the `'schema-validate'` drift detector to
+   * re-parse the file's contents. `null` disables schema validation even when
+   * `driftDetection === 'schema-validate'` (advisory-only mode).
+   */
+  schema?: ZodTypeAny | null;
+  /**
+   * Numeric merge precedence within the cascade. Higher wins.
+   *
+   * Canonical values:
+   * - `0`  — defaults / metadata (NOT part of the merge chain)
+   * - `10` — global
+   * - `20` — project
+   */
+  mergePrecedence: number;
+  /** Drift-detection strategy to apply to this entry. */
+  driftDetection: DriftDetection;
+  /** Optional default values used as the baseline for `'value-diff'` drift detection. */
+  defaults?: Record<string, unknown>;
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Built-in manifest entries (4 canonical CLEO files)
+// ───────────────────────────────────────────────────────────────────────────
+
+/**
+ * Manifest entry for `<project>/.cleo/project-info.json`.
+ *
+ * Metadata channel (NOT part of the merge cascade). Schema-validated on
+ * read because the file is consumer state with a stable shape.
+ *
+ * @task T9876
+ */
+export const PROJECT_INFO_MANIFEST: ConfigManifestEntry = {
+  id: 'project-info',
+  scope: 'metadata',
+  path: '.cleo/project-info.json',
+  mergePrecedence: 0,
+  driftDetection: 'schema-validate',
+};
+
+/**
+ * Manifest entry for `<project>/.cleo/project-context.json`.
+ *
+ * Metadata channel. Staleness-gated because the file is regenerated by
+ * project-detection scans and consumers care about freshness, not exact shape.
+ *
+ * @task T9876
+ */
+export const PROJECT_CONTEXT_MANIFEST: ConfigManifestEntry = {
+  id: 'project-context',
+  scope: 'metadata',
+  path: '.cleo/project-context.json',
+  mergePrecedence: 0,
+  driftDetection: 'staleness-gate',
+};
+
+/**
+ * Manifest entry for `<project>/.cleo/config.json` (project-scoped CleoConfig).
+ *
+ * Project scope; precedence 20 — wins over global. Schema-validated.
+ *
+ * @task T9876
+ */
+export const CLEO_CONFIG_MANIFEST: ConfigManifestEntry = {
+  id: 'cleo-config-project',
+  scope: 'project',
+  path: '.cleo/config.json',
+  mergePrecedence: 20,
+  driftDetection: 'schema-validate',
+};
+
+/**
+ * Manifest entry for `~/.cleo/config.json` (global CleoConfig).
+ *
+ * Global scope; precedence 10 — loses to project. Schema-validated.
+ *
+ * @task T9876
+ */
+export const GLOBAL_CLEO_CONFIG_MANIFEST: ConfigManifestEntry = {
+  id: 'cleo-config-global',
+  scope: 'global',
+  path: '~/.cleo/config.json',
+  mergePrecedence: 10,
+  driftDetection: 'schema-validate',
+};
+
+/**
+ * Frozen registry of all built-in manifest entries shipped with the contracts
+ * package. Order is informational only — consumers MUST sort by
+ * `mergePrecedence` when applying the cascade.
+ *
+ * @task T9876
+ */
+export const CONFIG_MANIFEST_ENTRIES: readonly ConfigManifestEntry[] = Object.freeze([
+  PROJECT_INFO_MANIFEST,
+  PROJECT_CONTEXT_MANIFEST,
+  GLOBAL_CLEO_CONFIG_MANIFEST,
+  CLEO_CONFIG_MANIFEST,
+]);
+
+// ───────────────────────────────────────────────────────────────────────────
+// Runtime validation schema
+// ───────────────────────────────────────────────────────────────────────────
+
+/**
+ * Zod schema for {@link ConfigManifestEntry}.
+ *
+ * Treats `schema` as `unknown` because `ZodTypeAny` instances cannot be
+ * validated through Zod itself without infinite recursion — schema-shape
+ * checking is the responsibility of the consumer that constructs the entry.
+ *
+ * @task T9876
+ */
+export const configManifestEntrySchema = z.object({
+  id: z.string().min(1),
+  scope: z.union([z.literal('global'), z.literal('project'), z.literal('metadata')]),
+  path: z.string().min(1),
+  schema: z.unknown().optional(),
+  mergePrecedence: z.number().int().nonnegative(),
+  driftDetection: z.union([
+    z.literal('schema-validate'),
+    z.literal('staleness-gate'),
+    z.literal('value-diff'),
+    z.literal('none'),
+  ]),
+  defaults: z.record(z.string(), z.unknown()).optional(),
+});