@cleocode/contracts 2026.5.130 → 2026.5.131

package/dist/tools/atomic.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Atomic-tool primitive contracts — the canonical I/O shapes for the CORE SDK
+ * tool layer (E3 · T11403 · SG-PACKAGE-ARCH).
+ *
+ * A **tool primitive** is the smallest stateless unit of side-effecting work an
+ * agent can perform — read a file, write a file, run a shell command, search,
+ * fetch a URL, edit a notebook cell. Each primitive is a PURE function of its
+ * typed input (no session/loop/global coupling); composing primitives into
+ * multi-step capabilities is the job of the SKILLS layer (`packages/skills`),
+ * not the tool layer. The implementations live in `packages/core/src/tools/*`
+ * (T11405-T11407) behind a single deny-first guardrail chokepoint; this module
+ * is their shared contract so `core`, `mcp-adapter`, `caamp`, and `cleo-os`
+ * agree on one shape and never redefine it.
+ *
+ * This is a NEW submodule (`@cleocode/contracts/tools/atomic`) kept separate
+ * from the squatted `contracts/src/tools/index.ts` (query/derivation helpers —
+ * see the E3 inventory note `e3-tools-inventory`). Types-only — no runtime
+ * logic (Gate 10 `contracts-purity`).
+ *
+ * @epic T11390
+ * @task T11403
+ * @saga T11387
+ */
+/**
+ * The atomic tool classes. Each class groups primitives that share a side-effect
+ * surface and therefore a guardrail policy (fs → path allowlist, shell → command
+ * denylist, net → egress policy, …).
+ */
+export declare const TOOL_CLASSES: readonly ["fs", "shell", "search", "net", "notebook"];
+/** One of the canonical {@link TOOL_CLASSES}. */
+export type ToolClass = (typeof TOOL_CLASSES)[number];
+/**
+ * Descriptor for a single registered tool primitive. The registry of these is
+ * the SoT for "what atomic tools exist", consumed by the guardrail chokepoint
+ * and (optionally) by the MCP adapter's tool catalog (T11411).
+ */
+export interface ToolPrimitiveDescriptor {
+    /** Stable primitive name (e.g. `readFileText`, `executeShell`). */
+    readonly name: string;
+    /** The side-effect class this primitive belongs to. */
+    readonly class: ToolClass;
+    /** One-line statement of the single responsibility this primitive owns. */
+    readonly responsibility: string;
+    /**
+     * Whether the primitive is a pure function of its input with no
+     * session/loop/global state coupling. Atomic primitives MUST be `true`;
+     * the flag exists so the guardrail + lints can reject stateful drift.
+     */
+    readonly stateless: boolean;
+}
+/** Input for reading a file's text content. */
+export interface ReadFileInput {
+    /** Absolute path to read. */
+    readonly path: string;
+    /** Text encoding. Defaults to `utf8` in the implementation. */
+    readonly encoding?: 'utf8' | 'utf-8' | 'ascii' | 'latin1';
+}
+/** Result of a text read. */
+export interface ReadFileResult {
+    /** Absolute path that was read. */
+    readonly path: string;
+    /** File contents as text. */
+    readonly content: string;
+}
+/** Input for an atomic (tmp-then-rename) file write. */
+export interface WriteFileInput {
+    /** Absolute path to write. */
+    readonly path: string;
+    /** Content to write. */
+    readonly content: string;
+    /** Create parent directories if missing. Defaults to `true`. */
+    readonly createDirs?: boolean;
+}
+/** Result of a file write. */
+export interface WriteFileResult {
+    /** Absolute path that was written. */
+    readonly path: string;
+    /** Number of bytes written. */
+    readonly bytesWritten: number;
+}
+/** Input for an existence check. */
+export interface PathExistsInput {
+    /** Absolute path to test. */
+    readonly path: string;
+}
+/** Result of an existence check. */
+export interface PathExistsResult {
+    /** Whether the path exists. */
+    readonly exists: boolean;
+    /** What kind of entry it is, when it exists. */
+    readonly kind?: 'file' | 'directory' | 'other';
+}
+/** Input for a shell-command execution. */
+export interface ExecuteShellInput {
+    /** Executable to run (NOT a shell string — args are passed separately). */
+    readonly command: string;
+    /** Arguments passed to {@link ExecuteShellInput.command}. */
+    readonly args?: readonly string[];
+    /** Working directory. Defaults to `process.cwd()` in the implementation. */
+    readonly cwd?: string;
+    /** Extra environment variables merged over the inherited environment. */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Hard timeout in milliseconds; the process is killed when exceeded. */
+    readonly timeoutMs?: number;
+}
+/** Result of a shell-command execution. */
+export interface ExecuteShellResult {
+    /** Captured standard output. */
+    readonly stdout: string;
+    /** Captured standard error. */
+    readonly stderr: string;
+    /** Process exit code (0 = success). `null` when killed by signal/timeout. */
+    readonly code: number | null;
+}
+/** Input for a `git` invocation (a constrained {@link ExecuteShellInput}). */
+export interface RunGitInput {
+    /** Git arguments (e.g. `['status', '--porcelain']`). */
+    readonly args: readonly string[];
+    /** Repository working directory. */
+    readonly cwd?: string;
+    /** Hard timeout in milliseconds. */
+    readonly timeoutMs?: number;
+}
+/** Input for a content/path search primitive. */
+export interface SearchInput {
+    /** Pattern to search for (literal or regex per {@link SearchInput.isRegex}). */
+    readonly pattern: string;
+    /** Root directory to search under. */
+    readonly root: string;
+    /** Treat {@link SearchInput.pattern} as a regular expression. */
+    readonly isRegex?: boolean;
+    /** Cap on returned matches. */
+    readonly maxResults?: number;
+}
+/** A single search match. */
+export interface SearchMatch {
+    /** Absolute path of the matching file. */
+    readonly path: string;
+    /** 1-based line number of the match. */
+    readonly line: number;
+    /** The matching line's text. */
+    readonly text: string;
+}
+/** Result of a search. */
+export interface SearchResult {
+    /** Matches in deterministic (path, line) order. */
+    readonly matches: readonly SearchMatch[];
+    /** Whether {@link SearchInput.maxResults} truncated the results. */
+    readonly truncated: boolean;
+}
+/** Input for an outbound HTTP fetch primitive. */
+export interface FetchInput {
+    /** Absolute URL to fetch. */
+    readonly url: string;
+    /** HTTP method. Defaults to `GET`. */
+    readonly method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+    /** Request headers. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Request body (already serialized). */
+    readonly body?: string;
+    /** Hard timeout in milliseconds. */
+    readonly timeoutMs?: number;
+}
+/** Result of an HTTP fetch. */
+export interface FetchResult {
+    /** HTTP status code. */
+    readonly status: number;
+    /** Response headers. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** Response body as text. */
+    readonly body: string;
+}
+/** Input for a notebook-cell edit primitive. */
+export interface NotebookEditInput {
+    /** Absolute path to the `.ipynb` file. */
+    readonly path: string;
+    /** 0-based index of the cell to edit. */
+    readonly cellIndex: number;
+    /** New source for the cell. */
+    readonly source: string;
+}
+/** Result of a notebook-cell edit. */
+export interface NotebookEditResult {
+    /** Absolute path that was edited. */
+    readonly path: string;
+    /** The cell index that changed. */
+    readonly cellIndex: number;
+}
+/**
+ * The canonical atomic-tool primitives. Implementations in
+ * `packages/core/src/tools/*` register against these names; the MCP adapter
+ * (T11411) may derive its catalog from this list rather than hand-listing.
+ */
+export declare const ATOMIC_TOOL_PRIMITIVES: readonly ToolPrimitiveDescriptor[];
+//# sourceMappingURL=atomic.d.ts.map

package/dist/tools/atomic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic.d.ts","sourceRoot":"","sources":["../../src/tools/atomic.ts"],"names":[],"mappings":"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"}

package/dist/tools/atomic.js

@@ -0,0 +1,82 @@
+/**
+ * Atomic-tool primitive contracts — the canonical I/O shapes for the CORE SDK
+ * tool layer (E3 · T11403 · SG-PACKAGE-ARCH).
+ *
+ * A **tool primitive** is the smallest stateless unit of side-effecting work an
+ * agent can perform — read a file, write a file, run a shell command, search,
+ * fetch a URL, edit a notebook cell. Each primitive is a PURE function of its
+ * typed input (no session/loop/global coupling); composing primitives into
+ * multi-step capabilities is the job of the SKILLS layer (`packages/skills`),
+ * not the tool layer. The implementations live in `packages/core/src/tools/*`
+ * (T11405-T11407) behind a single deny-first guardrail chokepoint; this module
+ * is their shared contract so `core`, `mcp-adapter`, `caamp`, and `cleo-os`
+ * agree on one shape and never redefine it.
+ *
+ * This is a NEW submodule (`@cleocode/contracts/tools/atomic`) kept separate
+ * from the squatted `contracts/src/tools/index.ts` (query/derivation helpers —
+ * see the E3 inventory note `e3-tools-inventory`). Types-only — no runtime
+ * logic (Gate 10 `contracts-purity`).
+ *
+ * @epic T11390
+ * @task T11403
+ * @saga T11387
+ */
+// ---------------------------------------------------------------------------
+// Taxonomy
+// ---------------------------------------------------------------------------
+/**
+ * The atomic tool classes. Each class groups primitives that share a side-effect
+ * surface and therefore a guardrail policy (fs → path allowlist, shell → command
+ * denylist, net → egress policy, …).
+ */
+export const TOOL_CLASSES = ['fs', 'shell', 'search', 'net', 'notebook'];
+// ---------------------------------------------------------------------------
+// Canonical primitive registry (the SoT for "what atomic tools exist")
+// ---------------------------------------------------------------------------
+/**
+ * The canonical atomic-tool primitives. Implementations in
+ * `packages/core/src/tools/*` register against these names; the MCP adapter
+ * (T11411) may derive its catalog from this list rather than hand-listing.
+ */
+export const ATOMIC_TOOL_PRIMITIVES = [
+    { name: 'readFileText', class: 'fs', responsibility: 'Read a file as text', stateless: true },
+    { name: 'readJson', class: 'fs', responsibility: 'Read + parse a JSON file', stateless: true },
+    {
+        name: 'writeFileAtomic',
+        class: 'fs',
+        responsibility: 'Atomically write a file (tmp-then-rename)',
+        stateless: true,
+    },
+    {
+        name: 'pathExists',
+        class: 'fs',
+        responsibility: 'Test path existence + kind',
+        stateless: true,
+    },
+    {
+        name: 'executeShell',
+        class: 'shell',
+        responsibility: 'Run a command with explicit cwd/env/timeout',
+        stateless: true,
+    },
+    { name: 'runGit', class: 'shell', responsibility: 'Run a git subcommand', stateless: true },
+    {
+        name: 'search',
+        class: 'search',
+        responsibility: 'Search content/paths under a root',
+        stateless: true,
+    },
+    {
+        name: 'fetch',
+        class: 'net',
+        responsibility: 'Perform an outbound HTTP request',
+        stateless: true,
+    },
+    {
+        name: 'notebookEdit',
+        class: 'notebook',
+        responsibility: 'Replace a notebook cell source',
+        stateless: true,
+    },
+];
+//# sourceMappingURL=atomic.js.map

package/dist/tools/atomic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic.js","sourceRoot":"","sources":["../../src/tools/atomic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAU,CAAC;AA+LlF,8EAA8E;AAC9E,uEAAuE;AACvE,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAuC;IACxE,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,qBAAqB,EAAE,SAAS,EAAE,IAAI,EAAE;IAC7F,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,0BAA0B,EAAE,SAAS,EAAE,IAAI,EAAE;IAC9F;QACE,IAAI,EAAE,iBAAiB;QACvB,KAAK,EAAE,IAAI;QACX,cAAc,EAAE,2CAA2C;QAC3D,SAAS,EAAE,IAAI;KAChB;IACD;QACE,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE,IAAI;QACX,cAAc,EAAE,4BAA4B;QAC5C,SAAS,EAAE,IAAI;KAChB;IACD;QACE,IAAI,EAAE,cAAc;QACpB,KAAK,EAAE,OAAO;QACd,cAAc,EAAE,6CAA6C;QAC7D,SAAS,EAAE,IAAI;KAChB;IACD,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,SAAS,EAAE,IAAI,EAAE;IAC3F;QACE,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,QAAQ;QACf,cAAc,EAAE,mCAAmC;QACnD,SAAS,EAAE,IAAI;KAChB;IACD;QACE,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,KAAK;QACZ,cAAc,EAAE,kCAAkC;QAClD,SAAS,EAAE,IAAI;KAChB;IACD;QACE,IAAI,EAAE,cAAc;QACpB,KAAK,EAAE,UAAU;QACjB,cAAc,EAAE,gCAAgC;QAChD,SAAS,EAAE,IAAI;KAChB;CACO,CAAC"}

package/dist/tools/composite.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Composite meta-tool contracts — typed I/O shapes for repo-structure
+ * velocity-multiplier tools (T11484 · DHQ-027/032 · E-CORE-SELF-TOOLING).
+ *
+ * A **composite tool** COMPOSES atomic primitives (`@cleocode/contracts/tools/
+ * atomic` — fs/shell/search) plus repo-structure knowledge into one guarded,
+ * deterministic, multi-step operation that runs WITHOUT an LLM and returns a
+ * typed result. Per the TOOL-vs-SKILL discriminator (T11456 epic), that makes
+ * these TOOLs (typed return, no agent reasoning), NOT skills (`packages/skills`
+ * markdown capabilities).
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * PLACEMENT STATUS (read before implementing the runtime)
+ * ─────────────────────────────────────────────────────────────────────────────
+ * These are the CONTRACTS ONLY. The runtime implementations are intentionally
+ * DEFERRED to epic **T11456** (TOOLS canonical structure), because a composite
+ * tool cannot be CORRECTLY placed/named/registered until T11456 lands:
+ *
+ *   - The atomic-tool boundary (`ATOMIC_TOOL_BOUNDARY` in `boundary.ts`, CI
+ *     Gate 11) restricts `packages/core/src/tools/` to ATOMIC, STATELESS
+ *     primitives (the 5 `TOOL_CLASSES`: fs/shell/search/net/notebook). These
+ *     composites are multi-step and repo-structure-aware — NOT atomic primitives
+ *     — so that home is wrong for them.
+ *   - `packages/skills/` (the boundary's `skillsHome`) holds agent-facing
+ *     SKILL.md markdown, not executable TS — also wrong.
+ *   - T11456 defines the missing structure these tools NEED: a closed
+ *     `ToolCategory` enum (it reserves `vcs`/`workflow`/`agent` — the categories
+ *     these compose), strict `<scope>_<category>_<operation>` naming, a
+ *     `ToolDescriptor` zod schema, and a `ToolRegistry` with project>global>core
+ *     precedence. Authoring the runtime + a category BEFORE that epic would
+ *     force a placement T11456 must then rework.
+ *
+ * Shipping the contracts now is the sound, additive, non-blocked unit: it pins
+ * the I/O shape (and enumerates every breakage/wiring class each tool owns) so
+ * the T11456 registry has a stable surface to register against. Types-only — no
+ * runtime logic (CI Gate 10 `contracts-purity`).
+ *
+ * @epic T11480
+ * @task T11484
+ * @see T11456 — TOOLS canonical structure (runtime home + registry + naming)
+ */
+/**
+ * The seven breakage classes a module relocation MUST repair atomically. A
+ * naive `git mv` fixes none of these; leaving any one unrepaired is a red build.
+ * The runtime asserts each class is handled and reports per-class edit counts.
+ */
+export declare const MODULE_RELOCATION_BREAKAGE_CLASSES: readonly ["relative-import-depth", "barrels", "js-form-and-dynamic-import", "mirror-test-dirs", "deprecations-yml", "doc-comments", "cross-package-importers"];
+/** One of the {@link MODULE_RELOCATION_BREAKAGE_CLASSES}. */
+export type ModuleRelocationBreakageClass = (typeof MODULE_RELOCATION_BREAKAGE_CLASSES)[number];
+/** Input for the `module-relocation` composite tool. */
+export interface ModuleRelocationInput {
+    /** Absolute (or repo-root-relative) path of the module to move. */
+    readonly fromPath: string;
+    /** Destination path for the module. */
+    readonly toPath: string;
+    /** Repository root the operation is scoped to. */
+    readonly repoRoot: string;
+    /**
+     * Leave a re-export shim at {@link ModuleRelocationInput.fromPath} that
+     * re-exports from the new location (for a deprecation cycle) instead of
+     * rewriting every importer. Defaults to `false` (rewrite importers).
+     */
+    readonly leaveShim?: boolean;
+    /** Preview the edit plan without writing. Defaults to `false`. */
+    readonly dryRun?: boolean;
+}
+/** Per-class summary of the edits a relocation made (or would make). */
+export interface ModuleRelocationClassReport {
+    /** Which breakage class this entry summarises. */
+    readonly class: ModuleRelocationBreakageClass;
+    /** Repo-relative files edited for this class. */
+    readonly files: readonly string[];
+    /** Total number of edits applied across {@link ModuleRelocationClassReport.files}. */
+    readonly edits: number;
+}
+/** Result of a `module-relocation` run. */
+export interface ModuleRelocationResult {
+    /** The module's new path. */
+    readonly toPath: string;
+    /** Whether a re-export shim was left at the old path. */
+    readonly shimLeft: boolean;
+    /** Whether this was a dry-run (no writes performed). */
+    readonly dryRun: boolean;
+    /** Per-breakage-class edit report (one entry per class, even when empty). */
+    readonly classes: readonly ModuleRelocationClassReport[];
+    /** Total repo-relative files touched across every class. */
+    readonly filesTouched: readonly string[];
+}
+/**
+ * The six wiring points a new workspace leaf MUST be threaded through. Missing
+ * any one yields a package that does not build, is not type-resolved, or is
+ * accidentally published. The runtime wires all six and reports each.
+ */
+export declare const ADD_WORKSPACE_PACKAGE_WIRING_POINTS: readonly ["deps", "tsconfig-refs", "build-mjs-buildpkg", "inline-maps", "boundary-entry", "private-no-readme"];
+/** One of the {@link ADD_WORKSPACE_PACKAGE_WIRING_POINTS}. */
+export type AddWorkspacePackageWiringPoint = (typeof ADD_WORKSPACE_PACKAGE_WIRING_POINTS)[number];
+/** Input for the `add-workspace-package` composite tool. */
+export interface AddWorkspacePackageInput {
+    /** Scoped package name, e.g. `@cleocode/foo`. */
+    readonly packageName: string;
+    /** Directory under `packages/` to create (defaults to the unscoped name). */
+    readonly dirName?: string;
+    /** Repository root the operation is scoped to. */
+    readonly repoRoot: string;
+    /** Packages that should depend on the new leaf (wires the `deps` point). */
+    readonly consumers?: readonly string[];
+    /** Preview the wiring plan without writing. Defaults to `false`. */
+    readonly dryRun?: boolean;
+}
+/** Per-point summary of how a wiring point was satisfied. */
+export interface AddWorkspacePackageWiringReport {
+    /** Which wiring point this entry summarises. */
+    readonly point: AddWorkspacePackageWiringPoint;
+    /** Repo-relative files created or edited for this point. */
+    readonly files: readonly string[];
+}
+/** Result of an `add-workspace-package` run. */
+export interface AddWorkspacePackageResult {
+    /** The created package's name. */
+    readonly packageName: string;
+    /** Repo-relative directory of the new leaf. */
+    readonly packageDir: string;
+    /** Whether this was a dry-run (no writes performed). */
+    readonly dryRun: boolean;
+    /** Per-wiring-point report (one entry per point, even when empty). */
+    readonly points: readonly AddWorkspacePackageWiringReport[];
+}
+//# sourceMappingURL=composite.d.ts.map

package/dist/tools/composite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../src/tools/composite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAMH;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,gKAerC,CAAC;AAEX,6DAA6D;AAC7D,MAAM,MAAM,6BAA6B,GAAG,CAAC,OAAO,kCAAkC,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhG,wDAAwD;AACxD,MAAM,WAAW,qBAAqB;IACpC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,wEAAwE;AACxE,MAAM,WAAW,2BAA2B;IAC1C,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,6BAA6B,CAAC;IAC9C,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,sFAAsF;IACtF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,SAAS,2BAA2B,EAAE,CAAC;IACzD,4DAA4D;IAC5D,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAMD;;;;GAIG;AACH,eAAO,MAAM,mCAAmC,gHAatC,CAAC;AAEX,8DAA8D;AAC9D,MAAM,MAAM,8BAA8B,GAAG,CAAC,OAAO,mCAAmC,CAAC,CAAC,MAAM,CAAC,CAAC;AAElG,4DAA4D;AAC5D,MAAM,WAAW,wBAAwB;IACvC,iDAAiD;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,6DAA6D;AAC7D,MAAM,WAAW,+BAA+B;IAC9C,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,8BAA8B,CAAC;IAC/C,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,gDAAgD;AAChD,MAAM,WAAW,yBAAyB;IACxC,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,SAAS,+BAA+B,EAAE,CAAC;CAC7D"}

package/dist/tools/composite.js

@@ -0,0 +1,88 @@
+/**
+ * Composite meta-tool contracts — typed I/O shapes for repo-structure
+ * velocity-multiplier tools (T11484 · DHQ-027/032 · E-CORE-SELF-TOOLING).
+ *
+ * A **composite tool** COMPOSES atomic primitives (`@cleocode/contracts/tools/
+ * atomic` — fs/shell/search) plus repo-structure knowledge into one guarded,
+ * deterministic, multi-step operation that runs WITHOUT an LLM and returns a
+ * typed result. Per the TOOL-vs-SKILL discriminator (T11456 epic), that makes
+ * these TOOLs (typed return, no agent reasoning), NOT skills (`packages/skills`
+ * markdown capabilities).
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * PLACEMENT STATUS (read before implementing the runtime)
+ * ─────────────────────────────────────────────────────────────────────────────
+ * These are the CONTRACTS ONLY. The runtime implementations are intentionally
+ * DEFERRED to epic **T11456** (TOOLS canonical structure), because a composite
+ * tool cannot be CORRECTLY placed/named/registered until T11456 lands:
+ *
+ *   - The atomic-tool boundary (`ATOMIC_TOOL_BOUNDARY` in `boundary.ts`, CI
+ *     Gate 11) restricts `packages/core/src/tools/` to ATOMIC, STATELESS
+ *     primitives (the 5 `TOOL_CLASSES`: fs/shell/search/net/notebook). These
+ *     composites are multi-step and repo-structure-aware — NOT atomic primitives
+ *     — so that home is wrong for them.
+ *   - `packages/skills/` (the boundary's `skillsHome`) holds agent-facing
+ *     SKILL.md markdown, not executable TS — also wrong.
+ *   - T11456 defines the missing structure these tools NEED: a closed
+ *     `ToolCategory` enum (it reserves `vcs`/`workflow`/`agent` — the categories
+ *     these compose), strict `<scope>_<category>_<operation>` naming, a
+ *     `ToolDescriptor` zod schema, and a `ToolRegistry` with project>global>core
+ *     precedence. Authoring the runtime + a category BEFORE that epic would
+ *     force a placement T11456 must then rework.
+ *
+ * Shipping the contracts now is the sound, additive, non-blocked unit: it pins
+ * the I/O shape (and enumerates every breakage/wiring class each tool owns) so
+ * the T11456 registry has a stable surface to register against. Types-only — no
+ * runtime logic (CI Gate 10 `contracts-purity`).
+ *
+ * @epic T11480
+ * @task T11484
+ * @see T11456 — TOOLS canonical structure (runtime home + registry + naming)
+ */
+// ---------------------------------------------------------------------------
+// module-relocation (DHQ-032)
+// ---------------------------------------------------------------------------
+/**
+ * The seven breakage classes a module relocation MUST repair atomically. A
+ * naive `git mv` fixes none of these; leaving any one unrepaired is a red build.
+ * The runtime asserts each class is handled and reports per-class edit counts.
+ */
+export const MODULE_RELOCATION_BREAKAGE_CLASSES = [
+    /** Relative-import depth (`../` vs `../../`) of the moved file's own imports. */
+    'relative-import-depth',
+    /** Barrel (`index.ts`) re-exports that referenced the old path. */
+    'barrels',
+    /** `.js`-suffixed specifiers AND dynamic `import()` specifiers. */
+    'js-form-and-dynamic-import',
+    /** The mirrored `__tests__/` directory for the moved module. */
+    'mirror-test-dirs',
+    /** `deprecations.yml` entries that pointed at the old path. */
+    'deprecations-yml',
+    /** Doc comments / `@see` / `@module` references to the old path. */
+    'doc-comments',
+    /** Cross-package importers that consumed the module via its package path. */
+    'cross-package-importers',
+];
+// ---------------------------------------------------------------------------
+// add-workspace-package (DHQ-027)
+// ---------------------------------------------------------------------------
+/**
+ * The six wiring points a new workspace leaf MUST be threaded through. Missing
+ * any one yields a package that does not build, is not type-resolved, or is
+ * accidentally published. The runtime wires all six and reports each.
+ */
+export const ADD_WORKSPACE_PACKAGE_WIRING_POINTS = [
+    /** `dependencies` / `devDependencies` of consuming packages. */
+    'deps',
+    /** The three `tsconfig` references: root refs, build tsconfig, path mapping. */
+    'tsconfig-refs',
+    /** The `buildPkg(...)` entry in the root `build.mjs` topological wave plan. */
+    'build-mjs-buildpkg',
+    /** esbuild/tsc inline source-map wiring for the new leaf. */
+    'inline-maps',
+    /** The `BOUNDARY_REGISTRY` entry in `packages/contracts/src/boundary.ts`. */
+    'boundary-entry',
+    /** `private: true` + no published README (internal-leaf publish hygiene). */
+    'private-no-readme',
+];
+//# sourceMappingURL=composite.js.map

package/dist/tools/composite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite.js","sourceRoot":"","sources":["../../src/tools/composite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,8EAA8E;AAC9E,8BAA8B;AAC9B,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG;IAChD,iFAAiF;IACjF,uBAAuB;IACvB,mEAAmE;IACnE,SAAS;IACT,mEAAmE;IACnE,4BAA4B;IAC5B,gEAAgE;IAChE,kBAAkB;IAClB,+DAA+D;IAC/D,kBAAkB;IAClB,oEAAoE;IACpE,cAAc;IACd,6EAA6E;IAC7E,yBAAyB;CACjB,CAAC;AA+CX,8EAA8E;AAC9E,kCAAkC;AAClC,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG;IACjD,gEAAgE;IAChE,MAAM;IACN,gFAAgF;IAChF,eAAe;IACf,+EAA+E;IAC/E,oBAAoB;IACpB,6DAA6D;IAC7D,aAAa;IACb,6EAA6E;IAC7E,gBAAgB;IAChB,6EAA6E;IAC7E,mBAAmB;CACX,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.5.130",
+  "version": "2026.5.131",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,6 +10,26 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./gateway": {
+      "types": "./dist/gateway.d.ts",
+      "import": "./dist/gateway.js"
+    },
+    "./gateway/rpc": {
+      "types": "./dist/gateway/rpc/index.d.ts",
+      "import": "./dist/gateway/rpc/index.js"
+    },
+    "./tools/atomic": {
+      "types": "./dist/tools/atomic.d.ts",
+      "import": "./dist/tools/atomic.js"
+    },
+    "./tools/composite": {
+      "types": "./dist/tools/composite.d.ts",
+      "import": "./dist/tools/composite.js"
+    },
+    "./gateway.js": {
+      "types": "./dist/gateway.d.ts",
+      "import": "./dist/gateway.js"
+    },
     "./provenance": {
       "types": "./dist/provenance.d.ts",
       "import": "./dist/provenance.js"
@@ -82,6 +102,18 @@
       "types": "./dist/nexus-tasks-bridge-ops.d.ts",
       "import": "./dist/nexus-tasks-bridge-ops.js"
     },
+    "./daemon": {
+      "types": "./dist/daemon/index.d.ts",
+      "import": "./dist/daemon/index.js"
+    },
+    "./daemon-ipc": {
+      "types": "./dist/daemon-ipc/index.d.ts",
+      "import": "./dist/daemon-ipc/index.js"
+    },
+    "./supervisor-ipc": {
+      "types": "./dist/supervisor-ipc/index.d.ts",
+      "import": "./dist/supervisor-ipc/index.js"
+    },
     "./dispatch/*": {
       "types": "./dist/dispatch/*.d.ts",
       "import": "./dist/dispatch/*.js"
@@ -146,7 +178,7 @@
   "dependencies": {
     "zod": "^4.3.6",
     "zod-to-json-schema": "^3.25.2",
-    "@cleocode/lafs": "2026.5.130"
+    "@cleocode/lafs": "2026.5.131"
   },
   "scripts": {
     "build": "tsc -b --force && node scripts/copy-assets.mjs && node scripts/emit-schemas.mjs",