@cleocode/contracts 2026.5.28 → 2026.5.29

package/src/graph.ts

@@ -158,6 +158,52 @@ export interface GraphNode {
   isExternal?: boolean;
 }
 
+// ---------------------------------------------------------------------------
+// Confidence label
+// ---------------------------------------------------------------------------
+
+/**
+ * Three-state confidence label for extracted edges.
+ *
+ * Complements the numeric `confidence` field with a categorical classification
+ * that maps to the pipeline's resolution tiers:
+ *
+ * - **`EXTRACTED`** (Tier 1): Statically verifiable from the AST — the
+ *   relationship is directly present in source. Covers `defines`, `imports`,
+ *   structural containment (`has_method`, `has_property`), and same-file
+ *   `calls` / `extends` / `implements`. Numeric confidence ≥ 0.90.
+ *
+ * - **`INFERRED`** (Tier 2a): Resolved through import-scoped analysis — the
+ *   target is reachable via a known import but requires cross-file name
+ *   resolution. Covers `accesses`, cross-file `calls`, and cross-file
+ *   `extends` / `implements`. Numeric confidence in range 0.80 – 0.89.
+ *
+ * - **`AMBIGUOUS`** (Tier 3): Global fallback resolution — the target was
+ *   found by scanning the entire repository index with no direct import
+ *   path. Multiple candidates may exist. Numeric confidence < 0.80.
+ *
+ * @since T1862
+ */
+export type GraphEdgeConfidenceLabel = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
+
+/**
+ * Map a numeric confidence value to a {@link GraphEdgeConfidenceLabel}.
+ *
+ * Thresholds align with the pipeline resolution tiers defined in
+ * `resolution-context.ts`:
+ * - ≥ 0.90 → `EXTRACTED`  (same-file 0.95, import-scoped 0.90, defines 1.0)
+ * - 0.80 – 0.89 → `INFERRED`   (accesses 0.80, heritage import-scoped 0.85)
+ * - < 0.80 → `AMBIGUOUS`  (global 0.50, speculative)
+ *
+ * @param confidence - Numeric confidence in range [0.0, 1.0]
+ * @returns The corresponding three-state label
+ */
+export function confidenceLabelFromNumeric(confidence: number): GraphEdgeConfidenceLabel {
+  if (confidence >= 0.9) return 'EXTRACTED';
+  if (confidence >= 0.8) return 'INFERRED';
+  return 'AMBIGUOUS';
+}
+
 // ---------------------------------------------------------------------------
 // Relation interface
 // ---------------------------------------------------------------------------
@@ -168,6 +214,11 @@ export interface GraphNode {
  * The `source` and `target` fields reference node IDs (see {@link GraphNode.id}).
  * Confidence reflects how certain the extractor is about this relationship,
  * from 0.0 (speculative) to 1.0 (statically verified).
+ *
+ * The `confidenceLabel` field provides a categorical three-state classification
+ * (see {@link GraphEdgeConfidenceLabel}) derived from the numeric `confidence`.
+ * Both fields are kept for backward compatibility: existing consumers that read
+ * the numeric field are unaffected; new consumers can use the label directly.
  */
 export interface GraphRelation {
   /** ID of the originating node. */
@@ -186,6 +237,15 @@ export interface GraphRelation {
    * - `accesses`: 0.8 (field read/write, may be indirect)
    */
   confidence: number;
+  /**
+   * Three-state categorical label derived from the numeric `confidence` tier.
+   *
+   * Optional for backward compatibility with callers that construct
+   * `GraphRelation` objects directly. Pipeline code SHOULD populate this
+   * field. See {@link GraphEdgeConfidenceLabel} and
+   * {@link confidenceLabelFromNumeric} for values and thresholds.
+   */
+  confidenceLabel?: GraphEdgeConfidenceLabel;
   /** Human-readable note explaining why this relation was emitted. */
   reason?: string;
 }

package/src/index.ts

@@ -212,6 +212,8 @@ export type {
   ConfigSource,
   DaemonLLMConfig,
   DateFormat,
+  DecisionsConfig,
+  DepsRequiredAt,
   EnforcementProfile,
   HierarchyConfig,
   LifecycleConfig,
@@ -257,6 +259,7 @@ export {
   ClassifierUnregisteredAgentError,
   createErrorResult,
   createSuccessResult,
+  DecisionValidatorFailedError,
   formatError,
   getErrorMessage,
   isErrorResult,
@@ -338,9 +341,10 @@ export {
   AGENT_TYPES,
   BRAIN_OBSERVATION_TYPES,
 } from './facade.js';
-// === Graph Intelligence Types (T512, T529) ===
+// === Graph Intelligence Types (T512, T529, T1862) ===
 export type {
   CommunityNode,
+  GraphEdgeConfidenceLabel,
   GraphNode,
   GraphNodeKind,
   GraphRelation,
@@ -350,6 +354,7 @@ export type {
   ProcessNode,
   SymbolIndex,
 } from './graph.js';
+export { confidenceLabelFromNumeric } from './graph.js';
 export type { AdapterHookProvider } from './hooks.js';
 export type { AdapterInstallProvider, InstallOptions, InstallResult } from './install.js';
 export type {
@@ -830,6 +835,9 @@ export type {
 } from './operations/session.js';
 // === Task Operation Types (T1425 — typed-dispatch migration) ===
 export type {
+  DepGraphIssue,
+  DepsTreeEdge,
+  DepsTreeNode,
   TasksAddParams,
   TasksAddResult,
   TasksAnalyzeQueryParams,
@@ -852,6 +860,11 @@ export type {
   TasksDeleteQueryResult,
   TasksDependsParams,
   TasksDependsResult,
+  // T1857 — dep-graph validation + tree rendering (T1855 guardrails)
+  TasksDepsTreeParams,
+  TasksDepsTreeResult,
+  TasksDepsValidateParams,
+  TasksDepsValidateResult,
   TasksFindParams,
   TasksFindResult,
   TasksHistoryParams,
@@ -1035,6 +1048,8 @@ export type {
   TaskRefPriority,
   TaskSummary,
 } from './results.js';
+// === SDK Tool Contract (Category B harness-agnostic SDK utilities — T1768 / ADR-064) ===
+export type { SdkTool, SdkToolIdentity } from './sdk-tool.js';
 // === Sentient Tier-2 Types (T1008) ===
 export type {
   ProposalCandidate,

package/src/operations/memory.ts

@@ -247,6 +247,16 @@ export interface MemoryDecisionFindParams {
   taskId?: string;
   /** Max results. */
   limit?: number;
+  /**
+   * T1830: when true, include AGT-* agent dispatch rows in results.
+   *
+   * By default `decision-find` excludes `decision_category = 'agent_dispatch'`
+   * rows so that architectural decisions are not buried by execution noise.
+   * Set to true to surface agent execution history.
+   *
+   * @default false
+   */
+  includeAgentDispatch?: boolean;
 }
 /** A single decision entry returned by the API. */
 export interface MemoryDecisionEntry {
@@ -317,6 +327,16 @@ export interface MemoryDecisionEntry {
    * `undefined` / `null` when the decision has never been validated.
    */
   validatorRunAt?: number | null;
+  /**
+   * Decision category (T1830).
+   *
+   * - `'architectural'`  — Architectural or technical decision (default).
+   * - `'agent_dispatch'` — AGT-* agent execution dispatch outcome.
+   * - `'other'`          — Miscellaneous.
+   *
+   * Defaults to `'architectural'` for rows written before T1830.
+   */
+  decisionCategory?: 'architectural' | 'agent_dispatch' | 'other';
 }
 /** Result of `memory.decision.find`. */
 export type MemoryDecisionFindResult = MemoryDecisionEntry[];

package/src/operations/tasks.ts

@@ -237,6 +237,114 @@ export interface TasksAnalyzeQueryParams {
  */
 export type TasksAnalyzeQueryResult = TaskAnalysisResult & { tierLimit: number };
 
+// tasks.deps.validate
+/**
+ * Parameters for `tasks.deps.validate`.
+ *
+ * @task T1857
+ * @epic T1855
+ */
+export interface TasksDepsValidateParams {
+  /** Scope to direct children of this epic (optional). */
+  epicId?: string;
+  /** Which tasks to include: all, open, or critical-priority only. @defaultValue 'all' */
+  scope?: 'all' | 'open' | 'critical';
+}
+
+/**
+ * A single dep-graph issue found by `tasks.deps.validate`.
+ *
+ * @task T1857
+ * @epic T1855
+ */
+export interface DepGraphIssue {
+  /** Machine-readable issue code. */
+  code: 'E_ORPHAN' | 'E_CIRCULAR' | 'E_CROSS_EPIC_GAP' | 'E_STALE_DEP' | 'E_MISSING_REF';
+  /** The task ID where the issue originates. */
+  taskId: string;
+  /** Human-readable description. */
+  message: string;
+  /** Related task IDs (dep IDs, cycle members, etc.). */
+  relatedIds?: string[];
+  /** Source epic ID (for E_CROSS_EPIC_GAP issues). */
+  epicA?: string;
+  /** Target epic ID (for E_CROSS_EPIC_GAP issues). */
+  epicB?: string;
+}
+
+/**
+ * Result of `tasks.deps.validate`.
+ *
+ * @task T1857
+ * @epic T1855
+ */
+export interface TasksDepsValidateResult {
+  /** True when no issues were found. */
+  valid: boolean;
+  /** All detected issues. Empty when valid. */
+  issues: DepGraphIssue[];
+  /** Human-readable summary line. */
+  summary: string;
+}
+
+// tasks.deps.tree
+/**
+ * Parameters for `tasks.deps.tree`.
+ *
+ * @task T1857
+ * @epic T1855
+ */
+export interface TasksDepsTreeParams {
+  /** Epic ID to visualize (required). */
+  epicId: string;
+  /** Output format. @defaultValue 'text' */
+  format?: 'text' | 'mermaid' | 'json';
+}
+
+/** A node in the deps tree JSON output. */
+export interface DepsTreeNode {
+  /** Task ID. */
+  id: string;
+  /** Task title. */
+  title: string;
+  /** Task status. */
+  status: string;
+  /** Direct dependency IDs. */
+  depends: string[];
+}
+
+/** An edge in the deps tree JSON output. */
+export interface DepsTreeEdge {
+  /** Source task ID (dependency). */
+  from: string;
+  /** Target task ID (dependent). */
+  to: string;
+}
+
+/**
+ * Result of `tasks.deps.tree`.
+ *
+ * @task T1857
+ * @epic T1855
+ */
+export interface TasksDepsTreeResult {
+  /** The epic ID the tree is scoped to. */
+  epicId: string;
+  /** Output format that was rendered. */
+  format: 'text' | 'mermaid' | 'json';
+  /**
+   * Rendered text or Mermaid output (when format is 'text' or 'mermaid').
+   * Null when format is 'json'.
+   */
+  rendered: string | null;
+  /** Structured node list (always populated). */
+  nodes: DepsTreeNode[];
+  /** Directed edges in the graph (dependency → dependent). */
+  edges: DepsTreeEdge[];
+  /** Task IDs on the critical path (longest dep chain), or empty if none. */
+  criticalPath: string[];
+}
+
 // tasks.impact
 export interface TasksImpactParams {
   change: string;
@@ -756,6 +864,8 @@ export type TasksOps = {
   readonly tree: readonly [TasksTreeDispatchParams, TasksTreeDispatchResult];
   readonly blockers: readonly [TasksBlockersQueryParams, TasksBlockersQueryResult];
   readonly depends: readonly [TasksDependsParams, TasksDependsResult];
+  readonly 'deps.validate': readonly [TasksDepsValidateParams, TasksDepsValidateResult];
+  readonly 'deps.tree': readonly [TasksDepsTreeParams, TasksDepsTreeResult];
   readonly analyze: readonly [TasksAnalyzeQueryParams, TasksAnalyzeQueryResult];
   readonly impact: readonly [TasksImpactParams, TasksImpactResult];
   readonly next: readonly [TasksNextQueryParams, TasksNextQueryResult];

package/src/sdk-tool.ts

@@ -0,0 +1,58 @@
+/**
+ * SdkTool contract — Category B harness-agnostic SDK utility.
+ *
+ * An SDK Tool is a harness-agnostic utility that every adapter, harness, and
+ * orchestration pathway MUST consume. SDK Tools:
+ *
+ * - MUST have zero harness-specific imports.
+ * - MUST expose a typed contract via `packages/contracts/src/`.
+ * - MUST be consumed by ALL adapters that invoke the relevant operation.
+ * - MUST be pure or side-effect-isolated (testable without running an agent).
+ * - SHOULD be deterministic given identical inputs.
+ *
+ * Canonical location: `packages/core/src/tools/sdk/`
+ *
+ * Distinct from Category A (Agent Tool — LLM-callable primitive registered in
+ * AgentToolRegistry) and Category C (Domain Utility — internal to a specific
+ * domain, not required cross-harness).
+ *
+ * @arch See ADR-064 (SDK Tools taxonomy: Category A Agent Tool vs Category B SDK Tool)
+ * @task T1815
+ * @epic T1768
+ */
+
+/**
+ * Identity metadata shared by all SDK Tools.
+ *
+ * Each SDK Tool MUST declare a stable `name` (used in diagnostics and audits),
+ * a human-readable `description`, and the semver-compatible `version` of the
+ * contract it exposes.
+ */
+export interface SdkToolIdentity {
+  /** Stable machine-readable identifier (kebab-case, e.g. `worktree-isolation`). */
+  name: string;
+  /** Human-readable description of the tool's purpose. */
+  description: string;
+  /**
+   * Contract version in `MAJOR.MINOR.PATCH` form.
+   *
+   * Increment MAJOR when the interface shape changes in a breaking way.
+   * Callers may guard on this field to detect incompatible contract upgrades.
+   */
+  version: string;
+}
+
+/**
+ * Base interface for all SDK Tools.
+ *
+ * Implementors extend this with operation-specific methods. The `identity`
+ * field is the only required member — it gives diagnostics and audit layers
+ * a stable handle on which SDK Tool is in play.
+ *
+ * @arch See ADR-064
+ * @task T1815
+ */
+export interface SdkTool {
+  /** Static identity metadata for this SDK Tool. */
+  readonly identity: SdkToolIdentity;
+}