@cleocode/contracts 2026.5.98 → 2026.5.100

package/src/index.ts

@@ -274,6 +274,8 @@ export type { CanonicalDomain, Gateway, Tier } from './dispatch/identity.js';
 export { CANONICAL_DOMAINS } from './dispatch/identity.js';
 // === Dispatch OperationDef + Resolution (T9954 — Phase 0b of SG-ARCH-SOLID / E-CONTRACTS-FOUNDATION) ===
 export type { OperationDef, Resolution } from './dispatch/operation-def.js';
+// === Dispatch OPERATIONS data + builder helpers (T10061 — T9833b / E-CLI-BOUNDARY / SG-ARCH-SOLID) ===
+export { defineDomain, defineOp, OPERATIONS } from './dispatch/operations-registry.js';
 // === DocsAccessor Contracts (T9063) ===
 export type {
   DocExportFormat,
@@ -1330,6 +1332,15 @@ export type {
   ProjectType,
   TestFramework,
 } from './project-context.js';
+// === ProjectTools Contracts (scaffold-project, doctor-project, scaffold-global — T10069 / T9835b) ===
+export type {
+  DoctorProjectOptions,
+  DoctorProjectResult,
+  ScaffoldGlobalResult,
+  ScaffoldProjectOptions,
+  ScaffoldProjectResult,
+  ScaffoldProjectStep,
+} from './project-tools.js';
 // === Provenance Graph Unions (T9955 — promoted from core/store/tasks-schema.ts) ===
 // Note: ReleaseChannel/ReleaseKind/ReleaseScheme/ReleaseStatus collide with the
 // existing `./release/channel.js` + `./release/plan.js` + `./task.js` exports
@@ -1719,6 +1730,40 @@ export type {
   TesseraTemplate,
   TesseraVariable,
 } from './tessera.js';
+export type { FetchBrainEntriesInput, FetchBrainEntriesOutput } from './tools/brain-fetch.js';
+export type { ObserveBrainInput, ObserveBrainOutput } from './tools/brain-observe.js';
+// === SDK Tool Contracts (T10068 / T10070 / T9835) ===
+// BrainTools (T10070 / T9835c)
+export type { SearchBrainInput, SearchBrainOutput } from './tools/brain-search.js';
+export type { TimelineBrainInput, TimelineBrainOutput } from './tools/brain-timeline.js';
+export type {
+  BuildRetrievalBundleInput,
+  BuildRetrievalBundleOutput,
+} from './tools/build-retrieval-bundle.js';
+// TaskTools (T10068 / T9835b)
+export type {
+  BuildTaskTreeInput,
+  BuildTaskTreeOptions,
+  BuildTaskTreeResult,
+} from './tools/build-task-tree.js';
+export type {
+  CriticalPathEdge,
+  CriticalPathNode,
+  CriticalPathResult,
+} from './tools/compute-critical-path.js';
+export type {
+  SchemaColumn,
+  SchemaDescriptor,
+  SchemaIndex,
+  SchemaTableDescriptor,
+} from './tools/describe-schema.js';
+export type { RenderTaskTreeInput } from './tools/render-task-tree.js';
+export type {
+  ScoreFactor,
+  ScoreTaskContext,
+  ScoreTaskInput,
+  ScoreTaskResult,
+} from './tools/score-task-priority.js';
 // === Transport (low-level wire protocol) ===
 export type {
   AdapterTransportProvider,

package/src/project-tools.ts

@@ -0,0 +1,117 @@
+/**
+ * ProjectTools contracts — input/output types for scaffold-project,
+ * doctor-project, and scaffold-global SDK tools.
+ *
+ * These are pure-functional, harness-agnostic operation contracts. Each
+ * tool function accepts an options bag and returns a typed result envelope —
+ * no I/O is performed inside the contract shapes themselves.
+ *
+ * Taxonomy: Category B SDK Tool (ADR-064).
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CORE-TOOLS T9835 (T9835b)
+ */
+
+import type { CheckResult, ScaffoldResult } from './scaffold-diagnostics.js';
+
+// ── scaffold-project ──────────────────────────────────────────────────
+
+/**
+ * Options for {@link ScaffoldProjectResult} — controls idempotency and override.
+ */
+export interface ScaffoldProjectOptions {
+  /**
+   * Absolute path to the project root (directory that contains `.cleo/`).
+   * Defaults to `process.cwd()` if omitted.
+   */
+  projectRoot?: string;
+  /**
+   * When `true`, re-writes files even if they already exist (mirrors the
+   * `--force` flag in `cleo init`).
+   *
+   * @default false
+   */
+  force?: boolean;
+}
+
+/**
+ * Result of a {@link scaffoldProject} call.
+ *
+ * Aggregates the individual {@link ScaffoldResult} returned by each
+ * `ensure*` step so callers can inspect per-step outcomes without re-running
+ * discovery.
+ */
+export interface ScaffoldProjectResult {
+  /** Absolute project root that was operated on. */
+  projectRoot: string;
+  /** Per-step results, in canonical execution order. */
+  steps: ScaffoldProjectStep[];
+  /** Whether all steps completed without an exception (individual steps may still report `repaired`). */
+  success: boolean;
+  /** Aggregated human-readable summary (e.g. "3 created, 8 skipped"). */
+  summary: string;
+}
+
+/**
+ * One step within a {@link ScaffoldProjectResult}.
+ */
+export interface ScaffoldProjectStep {
+  /** Stable step name used in diagnostics (e.g. `"cleo-structure"`, `"config"`). */
+  name: string;
+  /** Outcome of the corresponding `ensure*` call. Absent when the step was skipped due to an error. */
+  result?: ScaffoldResult;
+  /** Non-null when the step threw an exception (logged but not fatal). */
+  error?: string;
+}
+
+// ── doctor-project ────────────────────────────────────────────────────
+
+/**
+ * Options for {@link doctorProject}.
+ */
+export interface DoctorProjectOptions {
+  /**
+   * Absolute path to the project root.
+   * Defaults to `process.cwd()` if omitted.
+   */
+  projectRoot?: string;
+  /**
+   * Override the global cleo home used for CLI-level checks.
+   * Defaults to `getCleoHome()` if omitted.
+   */
+  cleoHome?: string;
+}
+
+/**
+ * Result of a {@link doctorProject} call — aggregates all synchronous
+ * diagnostic checks into a flat list.
+ */
+export interface DoctorProjectResult {
+  /** Absolute project root that was inspected. */
+  projectRoot: string;
+  /** Flat list of all check outcomes, global + project-scoped. */
+  checks: CheckResult[];
+  /**
+   * Rolled-up exit-code style status:
+   * - `0`  — all checks passed
+   * - `50` — at least one warning, no failures
+   * - `52` — at least one failure
+   */
+  exitCode: 0 | 50 | 52;
+}
+
+// ── scaffold-global ───────────────────────────────────────────────────
+
+/**
+ * Result of a {@link scaffoldGlobal} call — mirrors the return shape of
+ * the underlying `ensureGlobalScaffold()` call with added provenance.
+ */
+export interface ScaffoldGlobalResult {
+  /** Outcome of `ensureGlobalHome()`. */
+  home: ScaffoldResult;
+  /** Outcome of `ensureGlobalTemplates()`. */
+  templates: ScaffoldResult;
+  /** Outcome of `ensureCleoOsHub()`. */
+  cleoosHub: ScaffoldResult;
+  /** Whether all three steps completed without throwing. */
+  success: boolean;
+}

package/src/tools/brain-fetch.ts

@@ -0,0 +1,25 @@
+/**
+ * Contract types for the fetchBrainEntries SDK tool.
+ *
+ * @arch SDK Tool (Category B) — harness-agnostic, pure-functional wrapper
+ * @task T10070
+ * @epic T9835
+ */
+
+import type { FetchBrainEntriesParams, FetchBrainEntriesResult } from '../memory/fetch.js';
+
+export type { FetchBrainEntriesParams, FetchBrainEntriesResult };
+
+/** Input accepted by the fetchBrainEntries SDK tool. */
+export interface FetchBrainEntriesInput {
+  /** Project root directory for DB resolution. */
+  projectRoot: string;
+  /** Fetch parameters forwarded to fetchBrainEntries. */
+  params: FetchBrainEntriesParams;
+}
+
+/** Output produced by the fetchBrainEntries SDK tool. */
+export interface FetchBrainEntriesOutput {
+  /** Result from fetchBrainEntries. */
+  result: FetchBrainEntriesResult;
+}

package/src/tools/brain-observe.ts

@@ -0,0 +1,25 @@
+/**
+ * Contract types for the observeBrain SDK tool.
+ *
+ * @arch SDK Tool (Category B) — harness-agnostic, pure-functional wrapper
+ * @task T10070
+ * @epic T9835
+ */
+
+import type { ObserveBrainParams, ObserveBrainResult } from '../memory/observe.js';
+
+export type { ObserveBrainParams, ObserveBrainResult };
+
+/** Input accepted by the observeBrain SDK tool. */
+export interface ObserveBrainInput {
+  /** Project root directory for DB resolution. */
+  projectRoot: string;
+  /** Observation data forwarded to observeBrain. */
+  params: ObserveBrainParams;
+}
+
+/** Output produced by the observeBrain SDK tool. */
+export interface ObserveBrainOutput {
+  /** Result from observeBrain. */
+  result: ObserveBrainResult;
+}

package/src/tools/brain-search.ts

@@ -0,0 +1,25 @@
+/**
+ * Contract types for the searchBrain SDK tool.
+ *
+ * @arch SDK Tool (Category B) — harness-agnostic, pure-functional wrapper
+ * @task T10070
+ * @epic T9835
+ */
+
+import type { SearchBrainCompactParams, SearchBrainCompactResult } from '../memory/search.js';
+
+export type { SearchBrainCompactParams, SearchBrainCompactResult };
+
+/** Input accepted by the searchBrain SDK tool. */
+export interface SearchBrainInput {
+  /** Project root directory for DB resolution. */
+  projectRoot: string;
+  /** Search parameters forwarded to searchBrainCompact. */
+  params: SearchBrainCompactParams;
+}
+
+/** Output produced by the searchBrain SDK tool. */
+export interface SearchBrainOutput {
+  /** Compact search results from searchBrainCompact. */
+  result: SearchBrainCompactResult;
+}

package/src/tools/brain-timeline.ts

@@ -0,0 +1,25 @@
+/**
+ * Contract types for the timelineBrain SDK tool.
+ *
+ * @arch SDK Tool (Category B) — harness-agnostic, pure-functional wrapper
+ * @task T10070
+ * @epic T9835
+ */
+
+import type { TimelineBrainParams, TimelineBrainResult } from '../memory/timeline.js';
+
+export type { TimelineBrainParams, TimelineBrainResult };
+
+/** Input accepted by the timelineBrain SDK tool. */
+export interface TimelineBrainInput {
+  /** Project root directory for DB resolution. */
+  projectRoot: string;
+  /** Timeline parameters forwarded to timelineBrain. */
+  params: TimelineBrainParams;
+}
+
+/** Output produced by the timelineBrain SDK tool. */
+export interface TimelineBrainOutput {
+  /** Result from timelineBrain. */
+  result: TimelineBrainResult;
+}

package/src/tools/build-retrieval-bundle.ts

@@ -0,0 +1,25 @@
+/**
+ * Contract types for the buildRetrievalBundle SDK tool.
+ *
+ * @arch SDK Tool (Category B) — harness-agnostic, pure-functional wrapper
+ * @task T10070
+ * @epic T9835
+ */
+
+import type { RetrievalBundle, RetrievalRequest } from '../operations/memory.js';
+
+export type { RetrievalBundle, RetrievalRequest };
+
+/** Input accepted by the buildRetrievalBundle SDK tool. */
+export interface BuildRetrievalBundleInput {
+  /** Retrieval request forwarded to buildRetrievalBundle. */
+  req: RetrievalRequest;
+  /** Project root directory for DB resolution. */
+  projectRoot: string;
+}
+
+/** Output produced by the buildRetrievalBundle SDK tool. */
+export interface BuildRetrievalBundleOutput {
+  /** Fully-structured retrieval bundle with token accounting. */
+  bundle: RetrievalBundle;
+}

package/src/tools/build-task-tree.ts

@@ -0,0 +1,48 @@
+/**
+ * Contract types for the buildTaskTree SDK tool.
+ *
+ * @arch SDK Tool (Category B) — harness-agnostic, pure-functional
+ * @task T10068
+ * @epic T9835
+ */
+
+import type { TaskPriority } from '../task.js';
+import type { TaskTreeNode } from '../tasks.js';
+
+export type { TaskTreeNode };
+
+/** Minimal task shape required by buildTaskTree. */
+export interface BuildTaskTreeInput {
+  /** Unique task identifier. */
+  id: string;
+  /** Human-readable task title. */
+  title: string;
+  /** Current task status. */
+  status: string;
+  /** Task type classification. */
+  type?: string;
+  /** Task priority level. */
+  priority: TaskPriority;
+  /** ID of the parent task (null for root). */
+  parentId?: string | null;
+  /** Sort position within sibling scope. */
+  position?: number | null;
+  /** Dependency IDs. */
+  depends?: string[];
+  /** Additional labels. */
+  labels?: string[];
+}
+
+/** Options for buildTaskTree. */
+export interface BuildTaskTreeOptions {
+  /** When true, annotate each node with transitive blocker chains. */
+  withBlockers?: boolean;
+}
+
+/** Result of buildTaskTree. */
+export interface BuildTaskTreeResult {
+  /** Root-level tree nodes. */
+  tree: TaskTreeNode[];
+  /** Total number of nodes across all levels. */
+  totalNodes: number;
+}

package/src/tools/compute-critical-path.ts

@@ -0,0 +1,35 @@
+/**
+ * Contract types for the computeCriticalPath SDK tool.
+ *
+ * @arch SDK Tool (Category B) — harness-agnostic, pure-functional
+ * @task T10068
+ * @epic T9835
+ */
+
+/** A node in the dependency DAG. */
+export interface CriticalPathNode {
+  /** Unique task identifier. */
+  id: string;
+  /** Human-readable task title. */
+  title: string;
+  /** Current task status. */
+  status: string;
+  /** Dependency IDs (scoped to the same set of nodes). */
+  depends: string[];
+}
+
+/** A directed edge in the dependency DAG (dependency → dependent). */
+export interface CriticalPathEdge {
+  /** Source node ID (the dependency). */
+  from: string;
+  /** Target node ID (the dependent). */
+  to: string;
+}
+
+/** Result of computeCriticalPath. */
+export interface CriticalPathResult {
+  /** Ordered task IDs from path start to end (empty when graph has cycles). */
+  path: string[];
+  /** Length of the critical path. */
+  length: number;
+}

package/src/tools/describe-schema.ts

@@ -0,0 +1,43 @@
+/**
+ * Contract types for the describeSchema SDK tool.
+ *
+ * @arch SDK Tool (Category B) — harness-agnostic, pure-functional
+ * @task T10071
+ * @epic T9835
+ */
+
+/** A single column in a table descriptor. */
+export interface SchemaColumn {
+  /** Column name as declared in the drizzle schema. */
+  name: string;
+  /** SQLite data type (e.g. "TEXT", "INTEGER", "REAL", "BLOB"). */
+  type: string;
+  /** True when the column has a NOT NULL constraint. */
+  notNull: boolean;
+  /** True when the column is part of the primary key. */
+  primaryKey: boolean;
+}
+
+/** A single index in a table descriptor. */
+export interface SchemaIndex {
+  /** Index name as declared in the drizzle schema. */
+  name: string;
+  /** True when the index enforces uniqueness. */
+  unique: boolean;
+}
+
+/** Descriptor for one database table. */
+export interface SchemaTableDescriptor {
+  /** Table name as stored in SQLite (snake_case). */
+  name: string;
+  /** Ordered list of column descriptors. */
+  columns: SchemaColumn[];
+  /** List of indexes defined on this table (may be empty). */
+  indexes: SchemaIndex[];
+}
+
+/** Full output of describeSchema — all tables in the drizzle schema. */
+export interface SchemaDescriptor {
+  /** One entry per drizzle table exported from the schema barrel. */
+  tables: SchemaTableDescriptor[];
+}

package/src/tools/index.ts

@@ -0,0 +1,43 @@
+/**
+ * SDK Tool contract types.
+ *
+ * @arch Contracts barrel for Category B SDK Tools in packages/core/src/tools/
+ * @task T10068
+ * @task T10070
+ * @epic T9835
+ */
+
+export type { FetchBrainEntriesInput, FetchBrainEntriesOutput } from './brain-fetch.js';
+export type { ObserveBrainInput, ObserveBrainOutput } from './brain-observe.js';
+// === BrainTools (T10070 / T9835c) ===
+export type { SearchBrainInput, SearchBrainOutput } from './brain-search.js';
+export type { TimelineBrainInput, TimelineBrainOutput } from './brain-timeline.js';
+export type {
+  BuildRetrievalBundleInput,
+  BuildRetrievalBundleOutput,
+} from './build-retrieval-bundle.js';
+
+// === TaskTools (T10068 / T9835b) ===
+export type {
+  BuildTaskTreeInput,
+  BuildTaskTreeOptions,
+  BuildTaskTreeResult,
+} from './build-task-tree.js';
+export type {
+  CriticalPathEdge,
+  CriticalPathNode,
+  CriticalPathResult,
+} from './compute-critical-path.js';
+export type {
+  SchemaColumn,
+  SchemaDescriptor,
+  SchemaIndex,
+  SchemaTableDescriptor,
+} from './describe-schema.js';
+export type { RenderTaskTreeInput } from './render-task-tree.js';
+export type {
+  ScoreFactor,
+  ScoreTaskContext,
+  ScoreTaskInput,
+  ScoreTaskResult,
+} from './score-task-priority.js';

package/src/tools/render-task-tree.ts

@@ -0,0 +1,19 @@
+/**
+ * Contract types for the renderTaskTree SDK tools.
+ *
+ * @arch SDK Tool (Category B) — harness-agnostic, pure-functional
+ * @task T10068
+ * @epic T9835
+ */
+
+import type { CriticalPathEdge, CriticalPathNode } from './compute-critical-path.js';
+
+/** Input to both text and Mermaid renderers. */
+export interface RenderTaskTreeInput {
+  /** Task nodes to render. */
+  nodes: CriticalPathNode[];
+  /** Directed edges between nodes. */
+  edges: CriticalPathEdge[];
+  /** Task IDs on the critical path (highlighted in output). */
+  criticalPath: string[];
+}

package/src/tools/score-task-priority.ts

@@ -0,0 +1,59 @@
+/**
+ * Contract types for the scoreTask SDK tool.
+ *
+ * @arch SDK Tool (Category B) — harness-agnostic, pure-functional
+ * @task T10068
+ * @epic T9835
+ */
+
+import type { TaskPriority } from '../task.js';
+
+/** Minimal task shape required by scoreTask. */
+export interface ScoreTaskInput {
+  /** Unique task identifier. */
+  id: string;
+  /** Human-readable task title. */
+  title: string;
+  /** Task priority level. */
+  priority: TaskPriority;
+  /** Phase slug this task belongs to. */
+  phase?: string;
+  /** Dependency IDs. */
+  depends?: string[];
+  /** ISO timestamp of task creation. */
+  createdAt?: string;
+  /** Labels for pattern matching. */
+  labels?: string[];
+}
+
+/** Context provided to scoreTask to enable phase-aware and dependency-aware scoring. */
+export interface ScoreTaskContext {
+  /** Current project phase slug (used for phase alignment bonus). */
+  currentPhase?: string | null;
+  /** Map of all task IDs to their statuses (used for dep readiness check). */
+  taskStatuses?: Map<string, string>;
+  /** Current timestamp (ms since epoch) — defaults to Date.now() when omitted. */
+  nowMs?: number;
+  /** Matched success patterns from BRAIN (optional bonus scoring). */
+  successPatterns?: Array<{ pattern: string }>;
+  /** Matched failure patterns from BRAIN (optional penalty scoring). */
+  failurePatterns?: Array<{ pattern: string }>;
+}
+
+/** A scoring factor contributing to the final score. */
+export interface ScoreFactor {
+  /** Factor name (e.g. "priority", "phaseAlignment"). */
+  name: string;
+  /** Numeric contribution (positive = bonus, negative = penalty). */
+  delta: number;
+  /** Human-readable explanation. */
+  detail: string;
+}
+
+/** Result of scoreTask. */
+export interface ScoreTaskResult {
+  /** Final computed score. */
+  score: number;
+  /** Individual scoring factors. */
+  factors: ScoreFactor[];
+}