@lucern/contracts 1.0.0 → 1.0.1

package/dist/function-registry/tasks.d.ts

@@ -1,21 +1,5 @@
 import { z } from 'zod';
 
-/**
- * MCP Tool Contract Definitions
- *
- * Machine-readable source of truth for all Lucern MCP tool names,
- * descriptions, parameters, and response schemas.
- *
- * CONTRACT SURFACE: These definitions are the external API for AI agents.
- * Renaming a tool or changing its description is a BREAKING CHANGE.
- *
- * Git-native naming rules (enforced by lint):
- *   1. Workflow tools use git verbs directly (add_worktree, merge, push, open_pull_request)
- *   2. Knowledge tools use epistemic verbs (create_belief, fork_belief, modulate_confidence)
- *   3. First sentence of description includes the git analog verb
- *   4. Description includes "Like `git X`" parenthetical
- *   5. Parameter names use domain terms (canonicalText, nodeId, baseRate)
- */
 type McpToolContract = {
     /** Stable tool name — breaking change to rename */
     name: string;
@@ -84,7 +68,7 @@ type FunctionConvexTarget = {
     outputProjection?: ContractOutputProjection;
 };
 type FunctionGatewayTarget = {
-    handler: "identity.whoami" | "beliefs.list" | "evidence.list" | "questions.list" | "tasks.create" | "tasks.list" | "tasks.update" | "tasks.complete";
+    handler: "identity.whoami" | "beliefs.list" | "evidence.list" | "questions.list" | "worktrees.get" | "tasks.create" | "tasks.list" | "tasks.update" | "tasks.complete";
 };
 
 declare const tasksContracts: readonly [{

package/dist/function-registry/tasks.js

@@ -3,30 +3,7 @@ import { v } from 'convex/values';
 
 // src/function-registry/helpers.ts
 
-// src/types/reasoning-method.ts
-var REASONING_METHODS = [
-  "deductive",
-  "inductive",
-  "abductive",
-  "analogical",
-  "causal",
-  "correlational",
-  "testimonial",
-  "statistical",
-  "implicit",
-  "pattern_match"
-];
-
-// src/lens-workflow.contract.ts
-var LENS_PERSPECTIVE_TYPES = [
-  "investigation",
-  "monitoring",
-  "analysis",
-  "comparison",
-  "taxonomy"
-];
-
-// src/tool-contracts.ts
+// src/tool-contracts.lifecycle.ts
 var CREATE_BELIEF = {
   name: "create_belief",
   description: "Commit a new belief (knowledge unit) to the reasoning graph. Like `git commit` \u2014 creates an atomic, traceable knowledge object with a prior. Creation stores the vacuous opinion `(0, 0, 1, a)`; use modulate_confidence to record the first evidential update.",
@@ -432,6 +409,8 @@ var FLAG_CONTRADICTION = {
   ontologyPrimitive: "belief",
   tier: "showcase"
 };
+
+// src/tool-contracts.worktrees.ts
 var ADD_WORKTREE = {
   name: "add_worktree",
   description: "Check out a branch into an active worktree for investigation. Like `git worktree add <branch>` \u2014 creates independent working state on a thematic branch. Beliefs committed within the worktree can be freely amended (draft code on a feature branch). When investigation is complete, `merge` integrates findings into main.",
@@ -647,6 +626,82 @@ var MERGE = {
   ontologyPrimitive: "worktree",
   tier: "showcase"
 };
+var PUSH = {
+  name: "push",
+  description: "Push scored beliefs from a merged worktree to other contexts. Like `git push` \u2014 makes local findings available on the remote. Only merged beliefs can be pushed. Publication makes findings visible to other projects, teams, or external consumers.",
+  parameters: {
+    worktreeId: {
+      type: "string",
+      description: "The merged worktree whose findings to push"
+    },
+    targetContext: {
+      type: "string",
+      description: "Where to push (e.g., 'portfolio', 'ic_review', 'external')"
+    },
+    beliefIds: {
+      type: "array",
+      description: "Optional subset of beliefs to push (default: all scored)"
+    }
+  },
+  required: ["worktreeId", "targetContext"],
+  response: {
+    description: "Push result",
+    fields: {
+      pushedCount: "number",
+      targetContext: "string",
+      pushedAt: "number"
+    }
+  },
+  ownerModule: "workflow-engine",
+  ontologyPrimitive: "worktree",
+  tier: "workhorse"
+};
+var OPEN_PULL_REQUEST = {
+  name: "open_pull_request",
+  description: "Open a pull request for peer review before merging a worktree. Like opening a `git pull request` \u2014 the worktree's findings are ready but await approval before merge. Reviewers can approve, request changes, or block the merge. This is the gate between draft work and scored knowledge.",
+  parameters: {
+    worktreeId: {
+      type: "string",
+      description: "The worktree to submit for review"
+    },
+    reviewers: {
+      type: "array",
+      description: "User IDs of requested reviewers"
+    },
+    summary: {
+      type: "string",
+      description: "Summary of findings and why they're ready for merge"
+    }
+  },
+  required: ["worktreeId", "summary"],
+  response: {
+    description: "The pull request",
+    fields: {
+      pullRequestId: "string",
+      worktreeId: "string",
+      status: "string \u2014 'pending_review'"
+    }
+  },
+  ownerModule: "workflow-engine",
+  ontologyPrimitive: "worktree",
+  tier: "showcase"
+};
+
+// src/types/reasoning-method.ts
+var REASONING_METHODS = [
+  "deductive",
+  "inductive",
+  "abductive",
+  "analogical",
+  "causal",
+  "correlational",
+  "testimonial",
+  "statistical",
+  "implicit",
+  "pattern_match"
+];
+
+// src/tool-contracts.graph.ts
 var QUERY_LINEAGE = {
   name: "query_lineage",
   description: "Trace a belief's full ancestry \u2014 every fork, score, and confidence modulation. Like `git log --graph`. Returns the complete evolution chain showing how understanding developed over time. Lineage is permanent and can never be erased (Invariant #3).",
@@ -846,6 +901,39 @@ var FIND_CONTRADICTIONS = {
   ontologyPrimitive: "belief",
   tier: "showcase"
 };
+var BISECT_CONFIDENCE = {
+  name: "bisect_confidence",
+  description: "Find when a belief's confidence diverged from reality. Like `git bisect` \u2014 binary search through the credence history to find the inflection point. Given a belief that is now known to be wrong (or right), traces back through confidence modulations to identify which evidence or event caused the divergence.",
+  parameters: {
+    nodeId: { type: "string", description: "The belief to bisect" },
+    expectedDirection: {
+      type: "string",
+      description: "Was confidence too high or too low?",
+      enum: ["overconfident", "underconfident"]
+    },
+    timeRange: {
+      type: "object",
+      description: "Optional time range to search within: { start: number, end: number }"
+    }
+  },
+  required: ["nodeId", "expectedDirection"],
+  response: {
+    description: "The inflection point in confidence history",
+    fields: {
+      beliefId: "string \u2014 canonical belief ID",
+      expectedDirection: "string \u2014 overconfident | underconfident",
+      inflectionEntry: "object \u2014 the confidence modulation where divergence began",
+      triggerEvent: "string | null \u2014 what caused the divergence",
+      confidenceBefore: "number | null",
+      confidenceAfter: "number | null",
+      totalEntries: "number",
+      inflectionIndex: "number | null"
+    }
+  },
+  ownerModule: "graph-search",
+  ontologyPrimitive: "belief",
+  tier: "showcase"
+};
 var CREATE_EDGE = {
   name: "create_edge",
   description: "Commit a typed relationship between two nodes in the reasoning graph. Like `git commit` \u2014 an atomic write that declares a dependency between nodes. Accepts any public epistemic edge type between public graph node refs so agents can author the full spine.",
@@ -973,6 +1061,17 @@ var BATCH_CREATE_EDGES = {
   ontologyPrimitive: "edge",
   tier: "workhorse"
 };
+
+// src/lens-workflow.contract.ts
+var LENS_PERSPECTIVE_TYPES = [
+  "investigation",
+  "monitoring",
+  "analysis",
+  "comparison",
+  "taxonomy"
+];
+
+// src/tool-contracts.nodes-lenses.ts
 var CREATE_EPISTEMIC_NODE = {
   name: "create_epistemic_node",
   description: "Commit a generic epistemic graph node. Like `git commit` \u2014 creates a canonical node in the public spine for topics, beliefs, evidence, questions, answers, sources, and entities.",
@@ -1293,99 +1392,8 @@ var REMOVE_LENS_FROM_TOPIC = {
   ontologyPrimitive: "lens",
   tier: "workhorse"
 };
-var PUSH = {
-  name: "push",
-  description: "Push scored beliefs from a merged worktree to other contexts. Like `git push` \u2014 makes local findings available on the remote. Only merged beliefs can be pushed. Publication makes findings visible to other projects, teams, or external consumers.",
-  parameters: {
-    worktreeId: {
-      type: "string",
-      description: "The merged worktree whose findings to push"
-    },
-    targetContext: {
-      type: "string",
-      description: "Where to push (e.g., 'portfolio', 'ic_review', 'external')"
-    },
-    beliefIds: {
-      type: "array",
-      description: "Optional subset of beliefs to push (default: all scored)"
-    }
-  },
-  required: ["worktreeId", "targetContext"],
-  response: {
-    description: "Push result",
-    fields: {
-      pushedCount: "number",
-      targetContext: "string",
-      pushedAt: "number"
-    }
-  },
-  ownerModule: "workflow-engine",
-  ontologyPrimitive: "worktree",
-  tier: "workhorse"
-};
-var OPEN_PULL_REQUEST = {
-  name: "open_pull_request",
-  description: "Open a pull request for peer review before merging a worktree. Like opening a `git pull request` \u2014 the worktree's findings are ready but await approval before merge. Reviewers can approve, request changes, or block the merge. This is the gate between draft work and scored knowledge.",
-  parameters: {
-    worktreeId: {
-      type: "string",
-      description: "The worktree to submit for review"
-    },
-    reviewers: {
-      type: "array",
-      description: "User IDs of requested reviewers"
-    },
-    summary: {
-      type: "string",
-      description: "Summary of findings and why they're ready for merge"
-    }
-  },
-  required: ["worktreeId", "summary"],
-  response: {
-    description: "The pull request",
-    fields: {
-      pullRequestId: "string",
-      worktreeId: "string",
-      status: "string \u2014 'pending_review'"
-    }
-  },
-  ownerModule: "workflow-engine",
-  ontologyPrimitive: "worktree",
-  tier: "showcase"
-};
-var BISECT_CONFIDENCE = {
-  name: "bisect_confidence",
-  description: "Find when a belief's confidence diverged from reality. Like `git bisect` \u2014 binary search through the credence history to find the inflection point. Given a belief that is now known to be wrong (or right), traces back through confidence modulations to identify which evidence or event caused the divergence.",
-  parameters: {
-    nodeId: { type: "string", description: "The belief to bisect" },
-    expectedDirection: {
-      type: "string",
-      description: "Was confidence too high or too low?",
-      enum: ["overconfident", "underconfident"]
-    },
-    timeRange: {
-      type: "object",
-      description: "Optional time range to search within: { start: number, end: number }"
-    }
-  },
-  required: ["nodeId", "expectedDirection"],
-  response: {
-    description: "The inflection point in confidence history",
-    fields: {
-      beliefId: "string \u2014 canonical belief ID",
-      expectedDirection: "string \u2014 overconfident | underconfident",
-      inflectionEntry: "object \u2014 the confidence modulation where divergence began",
-      triggerEvent: "string | null \u2014 what caused the divergence",
-      confidenceBefore: "number | null",
-      confidenceAfter: "number | null",
-      totalEntries: "number",
-      inflectionIndex: "number | null"
-    }
-  },
-  ownerModule: "graph-search",
-  ontologyPrimitive: "belief",
-  tier: "showcase"
-};
+
+// src/tool-contracts.intelligence-evidence.ts
 var DETECT_CONFIRMATION_BIAS = {
   name: "detect_confirmation_bias",
   description: "Detect confirmation bias in the evidence graph. Like `git diff --stat` for reasoning \u2014 analyzes the ratio of supporting vs challenging evidence per belief and flags beliefs where the evidence is suspiciously one-sided. Returns risk classification (critical/high/moderate/healthy).",
@@ -1684,6 +1692,8 @@ var LINK_EVIDENCE_TO_BELIEF = {
   ontologyPrimitive: "edge",
   tier: "workhorse"
 };
+
+// src/tool-contracts.questions-listing.ts
 var CREATE_QUESTION = {
   name: "create_question",
   description: "Commit an investigation question to the reasoning graph. Like `git issue` \u2014 creates a traceable question that drives research and evidence collection. Questions test beliefs and guide worktree investigation.",
@@ -2142,6 +2152,24 @@ var LIST_ALL_WORKTREES = {
   ontologyPrimitive: "worktree",
   tier: "showcase"
 };
+var GET_WORKTREE = {
+  name: "get_worktree",
+  description: "Get one worktree by ID. Like `git worktree list --porcelain <worktree>` \u2014 inspects one investigation branch without scanning the full pipeline inventory.",
+  parameters: {
+    worktreeId: { type: "string", description: "Canonical worktree ID to retrieve" },
+    id: { type: "string", description: "Legacy alias for worktreeId" }
+  },
+  required: ["worktreeId"],
+  response: {
+    description: "Single worktree record with pipeline metadata",
+    fields: {
+      worktree: "object \u2014 { worktreeId, title, topicId, status, hypothesis, campaign, lane, laneOrderInCampaign, orderInLane, dependsOn, blocks, gate }"
+    }
+  },
+  ownerModule: "workflow-engine",
+  ontologyPrimitive: "worktree",
+  tier: "workhorse"
+};
 var LIST_CAMPAIGNS = {
   name: "list_campaigns",
   description: "List compact pipeline campaigns with their nested lanes. Use this to see the top-level campaign > lane > worktree shape without pulling the full worktree inventory.",
@@ -2443,6 +2471,8 @@ var COMPILE_CONTEXT = {
   ontologyPrimitive: "graph",
   tier: "showcase"
 };
+
+// src/tool-contracts.policy-observation-task-topic.ts
 var CHECK_PERMISSION = {
   name: "check_permission",
   description: "Check whether a principal can read or mutate a topic scope. Like `git check-ref-format` for ACLs \u2014 validates whether the requested operation is allowed before execution.",
@@ -3178,6 +3208,8 @@ var GET_GRAPH_GAPS = {
   ontologyPrimitive: "graph",
   tier: "showcase"
 };
+
+// src/tool-contracts.ontology.ts
 var MANAGE_WRITE_POLICY = {
   name: "manage_write_policy",
   description: "Manage write policies for MCP mutation tools. Like `git config` for write permissions \u2014 sets per-topic or global policies that control which roles can mutate the graph.",
@@ -3517,6 +3549,8 @@ var RESOLVE_EFFECTIVE_ONTOLOGY = {
   ontologyPrimitive: "ontology",
   tier: "workhorse"
 };
+
+// src/tool-contracts.pipeline-coordination.ts
 var RECORD_SCOPE_LEARNING = {
   name: "record_scope_learning",
   description: "Write a structured learning entry into the epistemic spine. Like `git commit` for scope learnings \u2014 records evidence, can attach to a belief, and can open a follow-up belief/question in one atomic workflow.",
@@ -4196,6 +4230,8 @@ var BEGIN_BUILD_SESSION = {
   tier: "showcase",
   internal: true
 };
+
+// src/tool-contracts.ts
 var MCP_TOOL_CONTRACTS = {
   // Belief lifecycle (commit, amend, fork, archive)
   create_belief: CREATE_BELIEF,
@@ -4278,6 +4314,7 @@ var MCP_TOOL_CONTRACTS = {
   find_missing_questions: FIND_MISSING_QUESTIONS,
   // Listing & query (workhorse)
   list_beliefs: LIST_BELIEFS,
+  get_worktree: GET_WORKTREE,
   list_worktrees: LIST_WORKTREES,
   list_all_worktrees: LIST_ALL_WORKTREES,
   list_campaigns: LIST_CAMPAIGNS,
@@ -4481,6 +4518,7 @@ var MCP_WORKFLOW_PLATFORM_OPERATION_NAMES = [
   "match_entity_type",
   "resolve_effective_ontology",
   "add_worktree",
+  "get_worktree",
   "activate_worktree",
   "list_worktrees",
   "list_all_worktrees",