@cleocode/contracts 2.0.0

package/src/operations/tasks.ts

@@ -0,0 +1,279 @@
+/**
+ * Tasks Domain Operations (22 operations)
+ *
+ * Query operations: 10
+ * Mutate operations: 12
+ *
+ * SYNC: Canonical type definitions live in the CLI package at:
+ *   src/types/task.ts (TaskStatus, TaskPriority, Task, etc.)
+ * These MCP operation types are the API contract (wire format).
+ * Internal domain types must stay aligned with CLI definitions.
+ */
+
+/**
+ * Common task types (API contract — matches CLI src/types/task.ts)
+ */
+import type { TaskStatus } from '../status-registry.js';
+export type { TaskStatus };
+export type TaskPriority = 'low' | 'medium' | 'high' | 'critical';
+
+export interface TaskOp {
+  id: string;
+  title: string;
+  description: string;
+  status: TaskStatus;
+  priority?: TaskPriority;
+  parent?: string;
+  depends?: string[];
+  labels?: string[];
+  created: string;
+  updated: string;
+  completed?: string;
+  notes?: string[];
+}
+
+export interface MinimalTask {
+  id: string;
+  title: string;
+  status: TaskStatus;
+  parent?: string;
+}
+
+/**
+ * Query Operations
+ */
+
+// tasks.get
+export interface TasksGetParams {
+  taskId: string;
+}
+export type TasksGetResult = TaskOp;
+
+// tasks.list
+export interface TasksListParams {
+  parent?: string;
+  status?: TaskStatus;
+  priority?: TaskPriority;
+  type?: string;
+  phase?: string;
+  label?: string;
+  children?: boolean;
+  limit?: number;
+  offset?: number;
+  compact?: boolean;
+}
+export interface TasksListResult {
+  tasks: TaskOp[];
+  total: number;
+  filtered: number;
+}
+
+// tasks.find
+export interface TasksFindParams {
+  query: string;
+  limit?: number;
+}
+export type TasksFindResult = MinimalTask[];
+
+// tasks.exists
+export interface TasksExistsParams {
+  taskId: string;
+}
+export interface TasksExistsResult {
+  exists: boolean;
+  taskId: string;
+}
+
+// tasks.tree
+export interface TasksTreeParams {
+  rootId?: string;
+  depth?: number;
+}
+export interface TaskTreeNode {
+  task: TaskOp;
+  children: TaskTreeNode[];
+  depth: number;
+}
+export type TasksTreeResult = TaskTreeNode[];
+
+// tasks.blockers
+export interface TasksBlockersParams {
+  taskId: string;
+}
+export interface Blocker {
+  taskId: string;
+  title: string;
+  status: TaskStatus;
+  blockType: 'dependency' | 'parent' | 'gate';
+}
+export type TasksBlockersResult = Blocker[];
+
+// tasks.deps
+export interface TasksDepsParams {
+  taskId: string;
+  direction?: 'upstream' | 'downstream' | 'both';
+}
+export interface TaskDependencyNode {
+  taskId: string;
+  title: string;
+  status: TaskStatus;
+  distance: number;
+}
+export interface TasksDepsResult {
+  taskId: string;
+  upstream: TaskDependencyNode[];
+  downstream: TaskDependencyNode[];
+}
+
+// tasks.analyze
+export interface TasksAnalyzeParams {
+  epicId?: string;
+}
+export interface TriageRecommendation {
+  taskId: string;
+  title: string;
+  priority: number;
+  reason: string;
+  readiness: 'ready' | 'blocked' | 'pending';
+}
+export type TasksAnalyzeResult = TriageRecommendation[];
+
+// tasks.next
+export interface TasksNextParams {
+  epicId?: string;
+  count?: number;
+}
+export interface SuggestedTask {
+  taskId: string;
+  title: string;
+  score: number;
+  rationale: string;
+}
+export type TasksNextResult = SuggestedTask[];
+
+/**
+ * Mutate Operations
+ */
+
+// tasks.create
+export interface TasksCreateParams {
+  title: string;
+  description: string;
+  parent?: string;
+  depends?: string[];
+  priority?: TaskPriority;
+  labels?: string[];
+}
+export type TasksCreateResult = TaskOp;
+
+// tasks.update
+export interface TasksUpdateParams {
+  taskId: string;
+  title?: string;
+  description?: string;
+  status?: TaskStatus;
+  priority?: TaskPriority;
+  notes?: string;
+  parent?: string | null; // Set parent ID, or null/"" to promote to root
+  labels?: string[];
+  addLabels?: string[];
+  removeLabels?: string[];
+  depends?: string[];
+  addDepends?: string[];
+  removeDepends?: string[];
+  type?: string;
+  size?: string;
+}
+export type TasksUpdateResult = TaskOp;
+
+// tasks.complete
+export interface TasksCompleteParams {
+  taskId: string;
+  notes?: string;
+  archive?: boolean;
+}
+export interface TasksCompleteResult {
+  taskId: string;
+  completed: string;
+  archived: boolean;
+}
+
+// tasks.delete
+export interface TasksDeleteParams {
+  taskId: string;
+  force?: boolean;
+}
+export interface TasksDeleteResult {
+  taskId: string;
+  deleted: true;
+}
+
+// tasks.archive
+export interface TasksArchiveParams {
+  taskId?: string;
+  before?: string;
+}
+export interface TasksArchiveResult {
+  archived: number;
+  taskIds: string[];
+}
+
+// tasks.unarchive
+export interface TasksUnarchiveParams {
+  taskId: string;
+}
+export type TasksUnarchiveResult = TaskOp;
+
+// tasks.reparent
+export interface TasksReparentParams {
+  taskId: string;
+  newParent: string;
+}
+export type TasksReparentResult = TaskOp;
+
+// tasks.promote
+export interface TasksPromoteParams {
+  taskId: string;
+}
+export type TasksPromoteResult = TaskOp;
+
+// tasks.reorder
+export interface TasksReorderParams {
+  taskId: string;
+  position: number;
+}
+export interface TasksReorderResult {
+  taskId: string;
+  newPosition: number;
+}
+
+// tasks.restore (completed tasks) — alias: reopen
+export interface TasksReopenParams {
+  taskId: string;
+}
+export type TasksReopenResult = TaskOp;
+
+// tasks.start (begin working on a task)
+export interface TasksStartParams {
+  taskId: string;
+}
+export interface TasksStartResult {
+  taskId: string;
+  sessionId: string;
+  timestamp: string;
+}
+
+// tasks.stop (stop working on current task)
+export type TasksStopParams = Record<string, never>;
+export interface TasksStopResult {
+  stopped: true;
+  previousTask?: string;
+}
+
+// tasks.current (get currently active task)
+export type TasksCurrentParams = Record<string, never>;
+export interface TasksCurrentResult {
+  taskId: string | null;
+  since?: string;
+  sessionId?: string;
+}

package/src/operations/validate.ts

@@ -0,0 +1,199 @@
+/**
+ * Validate Domain Operations (11 operations)
+ *
+ * Query operations: 9
+ * Mutate operations: 2
+ */
+
+/**
+ * Common validation types
+ */
+export type ValidationSeverity = 'error' | 'warning' | 'info';
+
+export interface ValidationViolation {
+  rule: string;
+  severity: ValidationSeverity;
+  message: string;
+  field?: string;
+  value?: unknown;
+  expected?: unknown;
+  line?: number;
+}
+
+export interface ComplianceMetrics {
+  total: number;
+  passed: number;
+  failed: number;
+  score: number;
+  byProtocol: Record<string, { passed: number; failed: number }>;
+  bySeverity: Record<ValidationSeverity, number>;
+}
+
+/**
+ * Query Operations
+ */
+
+// validate.schema
+export interface ValidateSchemaParams {
+  fileType: 'todo' | 'config' | 'archive' | 'log' | 'manifest';
+  filePath?: string;
+}
+export interface ValidateSchemaResult {
+  valid: boolean;
+  schemaVersion: string;
+  violations: ValidationViolation[];
+}
+
+// validate.protocol
+export interface ValidateProtocolParams {
+  taskId: string;
+  protocolType:
+    | 'research'
+    | 'consensus'
+    | 'specification'
+    | 'decomposition'
+    | 'implementation'
+    | 'contribution'
+    | 'release';
+}
+export interface ValidateProtocolResult {
+  taskId: string;
+  protocol: string;
+  passed: boolean;
+  score: number;
+  violations: ValidationViolation[];
+  requirements: {
+    total: number;
+    met: number;
+    failed: number;
+  };
+}
+
+// validate.task
+export interface ValidateTaskParams {
+  taskId: string;
+  checkMode: 'basic' | 'strict' | 'anti-hallucination';
+}
+export interface ValidateTaskResult {
+  taskId: string;
+  valid: boolean;
+  violations: ValidationViolation[];
+  checks: {
+    idUniqueness: boolean;
+    titleDescriptionDifferent: boolean;
+    validStatus: boolean;
+    noFutureTimestamps: boolean;
+    noDuplicateDescription: boolean;
+  };
+}
+
+// validate.manifest
+export interface ValidateManifestParams {
+  entry?: string;
+  taskId?: string;
+}
+export interface ValidateManifestResult {
+  valid: boolean;
+  entry: {
+    id: string;
+    file: string;
+    exists: boolean;
+  };
+  violations: ValidationViolation[];
+}
+
+// validate.output
+export interface ValidateOutputParams {
+  taskId: string;
+  filePath: string;
+}
+export interface ValidateOutputResult {
+  taskId: string;
+  filePath: string;
+  valid: boolean;
+  checks: {
+    fileExists: boolean;
+    hasTaskHeader: boolean;
+    hasStatus: boolean;
+    hasSummary: boolean;
+    linkedToTask: boolean;
+  };
+  violations: ValidationViolation[];
+}
+
+// validate.compliance.summary
+export interface ValidateComplianceSummaryParams {
+  scope?: string;
+  since?: string;
+}
+export type ValidateComplianceSummaryResult = ComplianceMetrics;
+
+// validate.compliance.violations
+export interface ValidateComplianceViolationsParams {
+  severity?: ValidationSeverity;
+  protocol?: string;
+}
+export interface ValidateComplianceViolationsResult {
+  violations: Array<
+    ValidationViolation & {
+      taskId: string;
+      protocol: string;
+      timestamp: string;
+    }
+  >;
+  total: number;
+}
+
+// validate.test.status
+export interface ValidateTestStatusParams {
+  taskId?: string;
+}
+export interface ValidateTestStatusResult {
+  total: number;
+  passed: number;
+  failed: number;
+  skipped: number;
+  passRate: number;
+  byTask?: Record<string, { passed: number; failed: number }>;
+}
+
+// validate.test.coverage
+export interface ValidateTestCoverageParams {
+  taskId?: string;
+}
+export interface ValidateTestCoverageResult {
+  lineCoverage: number;
+  branchCoverage: number;
+  functionCoverage: number;
+  statementCoverage: number;
+  threshold: number;
+  meetsThreshold: boolean;
+}
+
+/**
+ * Mutate Operations
+ */
+
+// validate.compliance.record
+export interface ValidateComplianceRecordParams {
+  taskId: string;
+  result: ValidateProtocolResult;
+}
+export interface ValidateComplianceRecordResult {
+  taskId: string;
+  recorded: string;
+  metrics: ComplianceMetrics;
+}
+
+// validate.test.run
+export interface ValidateTestRunParams {
+  scope?: string;
+  pattern?: string;
+  parallel?: boolean;
+}
+export interface ValidateTestRunResult {
+  status: ValidateTestStatusResult;
+  coverage: ValidateTestCoverageResult;
+  duration: string;
+  output?: string;
+}

package/src/provider-paths.ts

@@ -0,0 +1,16 @@
+/**
+ * Path provider interface for CLEO provider adapters.
+ * Allows providers to declare their OS-specific directory locations.
+ * @task T5240
+ */
+
+export interface AdapterPathProvider {
+  /** Get the provider's global config directory (e.g., ~/.claude/) */
+  getProviderDir(): string;
+  /** Get the path to the provider's settings file, or null if N/A */
+  getSettingsPath(): string | null;
+  /** Get the directory where this provider installs agents, or null if N/A */
+  getAgentInstallDir(): string | null;
+  /** Get the path to a third-party memory DB if applicable, or null */
+  getMemoryDbPath(): string | null;
+}

package/src/results.ts

@@ -0,0 +1,207 @@
+/**
+ * Result types for system engine queries: dashboard, stats, log, context, sequence.
+ *
+ * These replace ad-hoc Record<string, unknown> patterns in system-engine.ts.
+ *
+ * @task T4631
+ * @task T4783
+ */
+
+import type { TaskRecord } from './task-record.js';
+
+/** Task summary counts used in dashboard and stats views. */
+export interface TaskSummary {
+  pending: number;
+  active: number;
+  blocked: number;
+  done: number;
+  cancelled: number;
+  total: number;
+  archived: number;
+  grandTotal: number;
+}
+
+/** Label frequency entry. */
+export interface LabelCount {
+  label: string;
+  count: number;
+}
+
+/** Dashboard result from system.dash query. */
+export interface DashboardResult {
+  project: string;
+  currentPhase: string | null;
+  summary: TaskSummary;
+  taskWork: {
+    currentTask: string | null;
+    task: TaskRecord | null;
+  };
+  activeSession: string | null;
+  highPriority: {
+    count: number;
+    tasks: TaskRecord[];
+  };
+  blockedTasks: {
+    count: number;
+    limit: number;
+    tasks: TaskRecord[];
+  };
+  recentCompletions: TaskRecord[];
+  topLabels: LabelCount[];
+}
+
+/** Current state counts used in stats results. */
+export interface StatsCurrentState {
+  pending: number;
+  active: number;
+  done: number;
+  blocked: number;
+  cancelled: number;
+  totalActive: number;
+  archived: number;
+  grandTotal: number;
+}
+
+/** Completion metrics for a given time period. */
+export interface StatsCompletionMetrics {
+  periodDays: number;
+  completedInPeriod: number;
+  createdInPeriod: number;
+  completionRate: number;
+}
+
+/** Activity metrics for a given time period. */
+export interface StatsActivityMetrics {
+  createdInPeriod: number;
+  completedInPeriod: number;
+  archivedInPeriod: number;
+}
+
+/** All-time cumulative statistics. */
+export interface StatsAllTime {
+  totalCreated: number;
+  totalCompleted: number;
+  totalCancelled: number;
+  totalArchived: number;
+  archivedCompleted: number;
+}
+
+/** Cycle time statistics. */
+export interface StatsCycleTimes {
+  averageDays: number | null;
+  samples: number;
+}
+
+/** Stats result from system.stats query. */
+export interface StatsResult {
+  currentState: StatsCurrentState;
+  byPriority: Record<string, number>;
+  byType: Record<string, number>;
+  byPhase: Record<string, number>;
+  completionMetrics: StatsCompletionMetrics;
+  activityMetrics: StatsActivityMetrics;
+  allTime: StatsAllTime;
+  cycleTimes: StatsCycleTimes;
+}
+
+/** Log query result from system.log query. */
+export interface LogQueryResult {
+  entries: Array<{
+    operation: string;
+    taskId?: string;
+    timestamp: string;
+    [key: string]: unknown;
+  }>;
+  pagination: {
+    total: number;
+    offset: number;
+    limit: number;
+    hasMore: boolean;
+  };
+}
+
+/** Context monitoring data from system.context query. */
+export interface ContextResult {
+  available: boolean;
+  status: string;
+  percentage: number;
+  currentTokens: number;
+  maxTokens: number;
+  timestamp: string | null;
+  stale: boolean;
+  sessions: Array<{
+    file: string;
+    sessionId: string | null;
+    percentage: number;
+    status: string;
+    timestamp: string;
+  }>;
+}
+
+/** Sequence counter data from system.sequence query. */
+export interface SequenceResult {
+  counter: number;
+  lastId: string;
+  checksum: string;
+  nextId: string;
+}
+
+// ============================================================================
+// Task Analysis & Dependency Result Types
+// ============================================================================
+
+/** Compact task reference used across analysis and dependency results. */
+export interface TaskRef {
+  id: string;
+  title: string;
+  status: string;
+}
+
+/** Task reference with optional priority (used in orchestrator/HITL contexts). */
+export type TaskRefPriority = Pick<TaskRef, 'id' | 'title'> & { priority?: string };
+
+/** Task with leverage score for prioritization. */
+export interface LeveragedTask {
+  id: string;
+  title: string;
+  leverage: number;
+  reason?: string;
+}
+
+/** Bottleneck task — blocks other tasks. */
+export interface BottleneckTask {
+  id: string;
+  title: string;
+  blocksCount: number;
+}
+
+/** Task analysis result from tasks.analyze. */
+export interface TaskAnalysisResult {
+  recommended: (LeveragedTask & { reason: string }) | null;
+  bottlenecks: BottleneckTask[];
+  tiers: {
+    critical: LeveragedTask[];
+    high: LeveragedTask[];
+    normal: LeveragedTask[];
+  };
+  metrics: {
+    totalTasks: number;
+    actionable: number;
+    blocked: number;
+    avgLeverage: number;
+  };
+}
+
+/** Single task dependency result from tasks.deps. */
+export interface TaskDepsResult {
+  taskId: string;
+  dependsOn: TaskRef[];
+  dependedOnBy: TaskRef[];
+  unresolvedDeps: string[];
+  allDepsReady: boolean;
+}
+
+/** Completion result — unblocked tasks after completing a task. */
+export interface CompleteTaskUnblocked {
+  unblockedTasks?: TaskRef[];
+}