@cleocode/contracts 2026.5.111 → 2026.5.113

package/dist/templates/__tests__/manifest.test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Contract tests for the TemplateManifest schema.
+ *
+ * Asserts:
+ *
+ * 1. A valid entry for every {@link TemplateKind} parses successfully.
+ * 2. An entry with an unknown `kind` is rejected.
+ * 3. An entry missing `installPath` is rejected.
+ * 4. The {@link PlaceholderSpec} `source` field is exhaustively typed —
+ *    every member of {@link PLACEHOLDER_SOURCES} parses, and a bogus
+ *    source value is rejected.
+ *
+ * @task T9875
+ * @epic T9874
+ * @saga T9855
+ */
+export {};
+//# sourceMappingURL=manifest.test.d.ts.map

package/dist/templates/__tests__/manifest.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.test.d.ts","sourceRoot":"","sources":["../../../src/templates/__tests__/manifest.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/templates/__tests__/manifest.test.js

@@ -0,0 +1,123 @@
+/**
+ * Contract tests for the TemplateManifest schema.
+ *
+ * Asserts:
+ *
+ * 1. A valid entry for every {@link TemplateKind} parses successfully.
+ * 2. An entry with an unknown `kind` is rejected.
+ * 3. An entry missing `installPath` is rejected.
+ * 4. The {@link PlaceholderSpec} `source` field is exhaustively typed —
+ *    every member of {@link PLACEHOLDER_SOURCES} parses, and a bogus
+ *    source value is rejected.
+ *
+ * @task T9875
+ * @epic T9874
+ * @saga T9855
+ */
+import { describe, expect, it } from 'vitest';
+import { PLACEHOLDER_SOURCES, PlaceholderSpecSchema, TEMPLATE_KINDS, TemplateManifestEntrySchema, } from '../manifest.js';
+/**
+ * Build a valid baseline entry parameterized by `kind` so each
+ * assertion below stays minimal.
+ */
+function baseEntry(kind) {
+    return {
+        id: `sample-${kind}`,
+        kind,
+        sourcePath: `packages/core/templates/${kind}s/sample.tmpl`,
+        installPath: `.cleo/${kind}s/sample`,
+        substitution: 'regex-tmpl',
+        placeholders: [
+            {
+                name: 'NODE_VERSION',
+                source: 'project-context',
+                sourcePath: 'engines.node',
+                defaultValue: 24,
+            },
+        ],
+        updateStrategy: 'overwrite-on-bump',
+    };
+}
+describe('TemplateManifestEntrySchema (T9875)', () => {
+    it('accepts a valid entry for every TemplateKind', () => {
+        for (const kind of TEMPLATE_KINDS) {
+            const entry = baseEntry(kind);
+            const parsed = TemplateManifestEntrySchema.parse(entry);
+            expect(parsed.kind, `kind '${kind}' must round-trip`).toBe(kind);
+            expect(parsed.installPath).toBe(entry.installPath);
+        }
+    });
+    it('rejects an entry with an unknown kind', () => {
+        const bogus = {
+            ...baseEntry('workflow'),
+            kind: 'not-a-real-kind',
+        };
+        const result = TemplateManifestEntrySchema.safeParse(bogus);
+        expect(result.success).toBe(false);
+    });
+    it('rejects an entry missing installPath', () => {
+        const { installPath: _drop, ...rest } = baseEntry('config');
+        const result = TemplateManifestEntrySchema.safeParse(rest);
+        expect(result.success).toBe(false);
+    });
+    it('accepts an entry whose placeholders array is empty', () => {
+        const entry = { ...baseEntry('doc'), placeholders: [] };
+        const result = TemplateManifestEntrySchema.safeParse(entry);
+        expect(result.success).toBe(true);
+    });
+    it('accepts a defaultValue of every supported literal type and null', () => {
+        const types = [
+            { defaultValue: 'string-default' },
+            { defaultValue: 42 },
+            { defaultValue: true },
+            { defaultValue: null },
+            {},
+        ];
+        for (const extra of types) {
+            const result = PlaceholderSpecSchema.safeParse({
+                name: 'X',
+                source: 'literal',
+                sourcePath: 'X',
+                ...extra,
+            });
+            expect(result.success, `defaultValue case ${JSON.stringify(extra)} must parse`).toBe(true);
+        }
+    });
+});
+describe('PlaceholderSpecSchema source enum (T9875)', () => {
+    it('exhaustively accepts every member of PLACEHOLDER_SOURCES', () => {
+        for (const source of PLACEHOLDER_SOURCES) {
+            const result = PlaceholderSpecSchema.safeParse({
+                name: 'PLACEHOLDER',
+                source,
+                sourcePath: 'some.path',
+            });
+            expect(result.success, `source '${source}' must parse`).toBe(true);
+        }
+    });
+    it('rejects an unknown source value', () => {
+        const result = PlaceholderSpecSchema.safeParse({
+            name: 'PLACEHOLDER',
+            source: 'not-a-source',
+            sourcePath: 'some.path',
+        });
+        expect(result.success).toBe(false);
+    });
+    it('rejects an empty name', () => {
+        const result = PlaceholderSpecSchema.safeParse({
+            name: '',
+            source: 'project-context',
+            sourcePath: 'some.path',
+        });
+        expect(result.success).toBe(false);
+    });
+    it('rejects an empty sourcePath', () => {
+        const result = PlaceholderSpecSchema.safeParse({
+            name: 'X',
+            source: 'project-context',
+            sourcePath: '',
+        });
+        expect(result.success).toBe(false);
+    });
+});
+//# sourceMappingURL=manifest.test.js.map

package/dist/templates/__tests__/manifest.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.test.js","sourceRoot":"","sources":["../../../src/templates/__tests__/manifest.test.ts"],"names":[],"mappings":"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"}

package/dist/templates/manifest.d.ts

@@ -0,0 +1,186 @@
+/**
+ * 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';
+/**
+ * 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 declare const TEMPLATE_KINDS: readonly ["workflow", "config", "agent", "skill", "provider", "doc"];
+/** Discriminator for the category of file a template represents. */
+export type TemplateKind = (typeof TEMPLATE_KINDS)[number];
+/**
+ * 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 declare const TEMPLATE_SUBSTITUTIONS: readonly ["regex-tmpl", "static", "json-merge"];
+/** Strategy the installer uses to materialize a template's `sourcePath`. */
+export type TemplateSubstitution = (typeof TEMPLATE_SUBSTITUTIONS)[number];
+/**
+ * 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 declare const TEMPLATE_UPDATE_STRATEGIES: readonly ["overwrite-on-bump", "diff-prompt", "immutable", "manifest-merge"];
+/** Reconciliation policy for an installed template on upgrade. */
+export type UpdateStrategy = (typeof TEMPLATE_UPDATE_STRATEGIES)[number];
+/**
+ * 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 declare const PLACEHOLDER_SOURCES: readonly ["project-context", "project-info", ".cleo/config", "~/.cleo/config", "tool-resolver", "literal"];
+/** Resolver source enum for {@link PlaceholderSpec.source}. */
+export type PlaceholderSource = (typeof PLACEHOLDER_SOURCES)[number];
+/**
+ * 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 declare const PlaceholderSpecSchema: z.ZodObject<{
+    name: z.ZodString;
+    source: z.ZodEnum<{
+        literal: "literal";
+        "project-info": "project-info";
+        "project-context": "project-context";
+        ".cleo/config": ".cleo/config";
+        "~/.cleo/config": "~/.cleo/config";
+        "tool-resolver": "tool-resolver";
+    }>;
+    sourcePath: z.ZodString;
+    defaultValue: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+}, z.core.$strip>;
+/**
+ * Zod-inferred input shape for a placeholder declaration.
+ *
+ * Identical to {@link PlaceholderSpec} — there are no schema transforms.
+ */
+export type PlaceholderSpecInput = z.infer<typeof PlaceholderSpecSchema>;
+/** Declared placeholder on a {@link TemplateManifestEntry}. */
+export type PlaceholderSpec = PlaceholderSpecInput;
+/**
+ * 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 declare const TemplateManifestEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        agent: "agent";
+        config: "config";
+        provider: "provider";
+        workflow: "workflow";
+        doc: "doc";
+        skill: "skill";
+    }>;
+    sourcePath: z.ZodString;
+    installPath: z.ZodString;
+    substitution: z.ZodEnum<{
+        static: "static";
+        "regex-tmpl": "regex-tmpl";
+        "json-merge": "json-merge";
+    }>;
+    placeholders: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        source: z.ZodEnum<{
+            literal: "literal";
+            "project-info": "project-info";
+            "project-context": "project-context";
+            ".cleo/config": ".cleo/config";
+            "~/.cleo/config": "~/.cleo/config";
+            "tool-resolver": "tool-resolver";
+        }>;
+        sourcePath: z.ZodString;
+        defaultValue: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    }, z.core.$strip>>;
+    updateStrategy: z.ZodEnum<{
+        "overwrite-on-bump": "overwrite-on-bump";
+        "diff-prompt": "diff-prompt";
+        immutable: "immutable";
+        "manifest-merge": "manifest-merge";
+    }>;
+}, z.core.$strip>;
+/**
+ * Zod-inferred input shape for a template manifest entry.
+ *
+ * Identical to {@link TemplateManifestEntry} — there are no schema transforms.
+ */
+export type TemplateManifestEntryInput = z.infer<typeof TemplateManifestEntrySchema>;
+/** Public type for a fully-validated template manifest entry. */
+export type TemplateManifestEntry = TemplateManifestEntryInput;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/templates/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/templates/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,sEAAuE,CAAC;AAEnG,oEAAoE;AACpE,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAI3D;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,iDAAkD,CAAC;AAEtF,4EAA4E;AAC5E,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAI3E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,8EAK7B,CAAC;AAEX,kEAAkE;AAClE,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC;AAIzE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,4GAOtB,CAAC;AAEX,+DAA+D;AAC/D,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;iBAmBhC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEzE,+DAA+D;AAC/D,MAAM,MAAM,eAAe,GAAG,oBAAoB,CAAC;AAInD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAetC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAErF,iEAAiE;AACjE,MAAM,MAAM,qBAAqB,GAAG,0BAA0B,CAAC"}

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.111",
+  "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.111"
+    "@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']);
+  });
+});