@lucern/contracts 0.3.0-alpha.0 → 0.3.0-alpha.1

package/dist/sdk-tools.contract.js

@@ -10,7 +10,7 @@ var LENS_PERSPECTIVE_TYPES = [
 // src/tool-contracts.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 mandatory prior. Creation stores the vacuous opinion `(0, 0, 1, a)`; use modulate_confidence to record the first evidential update.",
+  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.",
   parameters: {
     canonicalText: {
       type: "string",
@@ -22,7 +22,7 @@ var CREATE_BELIEF = {
     },
     baseRate: {
       type: "number",
-      description: "Required prior probability used to seed the vacuous opinion `(0, 0, 1, a)` at creation time."
+      description: "Prior probability used to seed the vacuous opinion `(0, 0, 1, a)` at creation time. Defaults to 0.5 when omitted."
     },
     beliefType: {
       type: "string",
@@ -33,7 +33,7 @@ var CREATE_BELIEF = {
       description: "Optional extra metadata merged into the node (e.g., { codeAnchors: ['path/to/file.ts'] } for coding intelligence)"
     }
   },
-  required: ["canonicalText", "baseRate"],
+  required: ["canonicalText"],
   response: {
     description: "The created canonical belief record",
     fields: {
@@ -96,7 +96,7 @@ var REFINE_BELIEF = {
 };
 var MODULATE_CONFIDENCE = {
   name: "modulate_confidence",
-  description: "Record a confidence change for a belief. Like `git commit` to the credence log \u2014 an atomic, append-only write. Each modulation is a new entry in the history, not an overwrite. Scoring happens via merge; this tool records the individual data points. Pass the full subjective-logic tuple (`belief`, `disbelief`, `uncertainty`, `baseRate`) directly. If a caller only has a scalar probability, use `@lucern/sdk` helpers `opinionFromBaseRate`, `opinionFromDogmatic`, or `opinionFromProjected` to name the intended interpretation before calling this tool. Triggers: evidence_added, evidence_removed, contradiction_detected, contradiction_resolved, agent_assessment, worktree_outcome, worktree_completed, fusion, discount, deduction, manual, decay.",
+  description: "Record a confidence change for a belief. Like `git commit` to the credence log \u2014 an atomic, append-only write. Each modulation is a new entry in the history, not an overwrite. Scoring happens via merge; this tool records the individual data points. Pass the full subjective-logic tuple (`belief`, `disbelief`, `uncertainty`, `baseRate`) directly. If a caller only has a scalar probability, use `@lucern/sdk` helpers `opinionFromBaseRate`, `opinionFromDogmatic`, or `opinionFromProjected` to name the intended interpretation before calling this tool. Every modulation must cite a truth-bearing artifact: triggeringEvidenceId, triggeringQuestionId, triggeringAnswerId, triggeringContradictionId, or triggeringWorktreeId. Triggers: evidence_added, evidence_removed, contradiction_detected, contradiction_resolved, agent_assessment, worktree_outcome, worktree_completed, fusion, discount, deduction.",
   parameters: {
     nodeId: { type: "string", description: "The belief to score" },
     belief: {
@@ -115,9 +115,9 @@ var MODULATE_CONFIDENCE = {
       type: "number",
       description: "Subjective-logic base rate `a` in [0, 1]. Required for tuple payloads."
     },
-    confidence: {
-      type: "number",
-      description: "Deprecated scalar confidence value in [0, 1]. Scalar-only payloads are rejected as AMBIGUOUS_SCALAR."
+    worktreeId: {
+      type: "string",
+      description: "Completed worktree that tested this belief when confidence policy requires merge-backed scoring."
     },
     trigger: {
       type: "string",
@@ -132,17 +132,43 @@ var MODULATE_CONFIDENCE = {
         "worktree_completed",
         "fusion",
         "discount",
-        "deduction",
-        "manual",
-        "decay"
+        "deduction"
       ]
     },
+    triggeringEvidenceId: {
+      type: "string",
+      description: "Evidence node that caused an evidence-triggered modulation"
+    },
+    triggeringQuestionId: {
+      type: "string",
+      description: "Answered question whose resolution supports this modulation"
+    },
+    triggeringAnswerId: {
+      type: "string",
+      description: "Answer node whose content supports this modulation"
+    },
+    triggeringContradictionId: {
+      type: "string",
+      description: "Contradiction record that caused a contradiction-triggered modulation"
+    },
+    triggeringWorktreeId: {
+      type: "string",
+      description: "Completed worktree whose outcome caused a worktree-triggered modulation"
+    },
     rationale: {
       type: "string",
       description: "Human-readable explanation of why confidence changed"
     }
   },
-  required: ["nodeId", "trigger", "rationale"],
+  required: [
+    "nodeId",
+    "belief",
+    "disbelief",
+    "uncertainty",
+    "baseRate",
+    "trigger",
+    "rationale"
+  ],
   response: {
     description: "Confidence modulation result",
     fields: {
@@ -336,7 +362,7 @@ var ADD_EVIDENCE = {
       description: "Optional extra metadata merged into the node (e.g., { codeAnchors: ['path/to/file.ts'], failedApproach: true } for coding intelligence)"
     }
   },
-  required: ["canonicalText", "targetNodeId"],
+  required: ["canonicalText", "targetNodeId", "reasoning"],
   response: {
     description: "The created evidence node and its edge",
     fields: {
@@ -417,9 +443,21 @@ var ADD_WORKTREE = {
       type: "string",
       description: "Optional domain pack whose shaping hooks should influence generated questions and tasks"
     },
-    executionOrder: {
+    campaign: {
+      type: "number",
+      description: "Top-level pipeline campaign number. Campaigns define the outer execution slice."
+    },
+    lane: {
+      type: "string",
+      description: "GitButler-aligned workstream lane name inside the campaign."
+    },
+    laneOrderInCampaign: {
+      type: "number",
+      description: "Ordering for this lane within its campaign."
+    },
+    orderInLane: {
       type: "number",
-      description: "Global execution order for this worktree"
+      description: "Position of this worktree inside its lane."
     },
     dependsOn: {
       type: "array",
@@ -1077,6 +1115,10 @@ var CREATE_EVIDENCE = {
       type: "object",
       description: "Optional metadata merged into the canonical evidence node"
     },
+    rationale: {
+      type: "string",
+      description: "Why this evidence should enter the reasoning graph"
+    },
     title: { type: "string", description: "Optional short title" },
     content: { type: "string", description: "Optional long-form content" },
     contentType: {
@@ -1085,7 +1127,7 @@ var CREATE_EVIDENCE = {
     },
     kind: { type: "string", description: "Optional evidence kind" }
   },
-  required: ["text"],
+  required: ["text", "rationale"],
   response: {
     description: "The created canonical evidence record",
     fields: {
@@ -1133,7 +1175,7 @@ var LIST_EVIDENCE = {
     limit: { type: "number", description: "Max results" },
     cursor: { type: "string", description: "Pagination cursor" }
   },
-  required: [],
+  required: ["topicId"],
   response: {
     description: "Canonical evidence page",
     fields: {
@@ -1318,6 +1360,7 @@ var ANSWER_QUESTION = {
   description: "Answer a question with optional evidence links. Like `git commit` on the question thread \u2014 records the answer and closes the loop with a canonical answered state.",
   parameters: {
     id: { type: "string", description: "Canonical question ID" },
+    topicId: { type: "string", description: "Topic scope for the answer" },
     text: { type: "string", description: "Answer text" },
     confidence: {
       type: "string",
@@ -1330,7 +1373,7 @@ var ANSWER_QUESTION = {
     },
     rationale: { type: "string", description: "Why this answer is credible" }
   },
-  required: ["id", "text"],
+  required: ["id", "topicId", "text"],
   response: {
     description: "Answer result",
     fields: {
@@ -1549,6 +1592,10 @@ var LIST_BELIEFS = {
     minConfidence: {
       type: "number",
       description: "Minimum confidence threshold"
+    },
+    limit: {
+      type: "number",
+      description: "Maximum results"
     }
   },
   required: ["topicId"],
@@ -1565,20 +1612,37 @@ var LIST_BELIEFS = {
 };
 var LIST_WORKTREES = {
   name: "list_worktrees",
-  description: "List all worktrees for a topic. Like `git worktree list` \u2014 shows active and completed investigation branches with their phase, status, and belief counts.",
+  description: "List all worktrees for a topic. Like `git worktree list` \u2014 shows active and completed investigation branches with lifecycle phase, pipeline campaign/lane, status, and belief counts.",
   parameters: {
     topicId: { type: "string", description: "Topic scope" },
     status: {
       type: "string",
       description: "Filter: active, merged, abandoned",
       enum: ["active", "merged", "abandoned"]
+    },
+    groupBy: {
+      type: "string",
+      description: "Optional grouping mode for the response.",
+      enum: ["campaign", "lane", "flat"]
+    },
+    lane: {
+      type: "string",
+      description: "Filter by GitButler-aligned lane name."
+    },
+    campaign: {
+      type: "number",
+      description: "Filter by top-level pipeline campaign number."
+    },
+    limit: {
+      type: "number",
+      description: "Maximum results to return."
     }
   },
   required: ["topicId"],
   response: {
-    description: "Worktrees with phase, status, belief count, and creation time",
+    description: "Worktrees with lifecycle phase, campaign, lane, status, belief count, and creation time",
     fields: {
-      worktrees: "array \u2014 { worktreeId, title, phase, status, beliefCount, createdAt }"
+      worktrees: "array \u2014 { worktreeId, title, phase, campaign, lane, laneOrderInCampaign, orderInLane, status, beliefCount, createdAt }"
     }
   },
   ownerModule: "workflow-engine",
@@ -1587,7 +1651,7 @@ var LIST_WORKTREES = {
 };
 var LIST_ALL_WORKTREES = {
   name: "list_all_worktrees",
-  description: "List ALL worktrees across ALL topics in one query. No topic scope required. Like `git worktree list --all` \u2014 returns the complete pipeline inventory with track, trackPosition, executionBand, dependencies, and status. Supports filtering by status, track, and executionBand. This is the PM's primary pipeline query \u2014 one call, full picture.",
+  description: "List ALL worktrees across ALL topics in one query. No topic scope required. Like `git worktree list --all` \u2014 returns the complete pipeline inventory with campaign, lane, lane order, dependencies, and status. Supports filtering by status, lane, and campaign. This is the PM's primary pipeline query \u2014 one call, full picture.",
   parameters: {
     status: {
       type: "string",
@@ -1605,13 +1669,18 @@ var LIST_ALL_WORKTREES = {
         "dismissed"
       ]
     },
-    track: {
+    lane: {
       type: "string",
-      description: "Filter by track name (e.g., 'ontology', 'tc-scope', 'control-plane', 'dev-portal', 'mcp-sdk-parity')"
+      description: "Filter by lane name (e.g., 'ontology', 'tc-scope', 'control-plane', 'dev-portal', 'mcp-sdk-parity')"
     },
-    executionBand: {
+    campaign: {
       type: "number",
-      description: "Filter by execution band number (e.g., 1, 2, 3). Returns only worktrees in that parallel execution group."
+      description: "Filter by campaign number (e.g., 1, 2, 3). Returns only worktrees in that campaign."
+    },
+    groupBy: {
+      type: "string",
+      description: "Optional grouping mode for the response.",
+      enum: ["campaign", "lane", "flat"]
     },
     limit: {
       type: "number",
@@ -1622,10 +1691,39 @@ var LIST_ALL_WORKTREES = {
   response: {
     description: "All worktrees across all topics with full pipeline metadata",
     fields: {
-      worktrees: "array \u2014 { worktreeId, title, topicId, topicName, phase, status, hypothesis, track, trackPosition, executionBand, executionOrder, dependsOn, blocks, gate, createdAt }",
+      worktrees: "array \u2014 { worktreeId, title, topicId, topicName, phase, status, hypothesis, campaign, lane, laneOrderInCampaign, orderInLane, dependsOn, blocks, gate, createdAt }",
       total: "number \u2014 total count after filtering",
-      tracks: "object \u2014 { trackName: count } summary of worktrees per track",
-      bands: "object \u2014 { bandNumber: count } summary of worktrees per execution band"
+      lanes: "object \u2014 { laneName: count } summary of worktrees per lane",
+      campaigns: "object \u2014 { campaignNumber: count } summary of worktrees per campaign"
+    }
+  },
+  ownerModule: "workflow-engine",
+  ontologyPrimitive: "worktree",
+  tier: "showcase"
+};
+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.",
+  parameters: {
+    topicId: {
+      type: "string",
+      description: "Optional topic scope."
+    },
+    status: {
+      type: "string",
+      description: "Optional worktree status filter before grouping campaigns and lanes."
+    },
+    limit: {
+      type: "number",
+      description: "Maximum worktrees to scan before grouping."
+    }
+  },
+  required: [],
+  response: {
+    description: "Pipeline campaigns with nested lane summaries.",
+    fields: {
+      campaigns: "array \u2014 { campaign, lanes: [{ lane, laneOrderInCampaign, worktreeCount, activeCount, readyCount, blockedCount, completedCount, nextWorktree }] }",
+      totalWorktrees: "number \u2014 total worktrees scanned after filtering"
     }
   },
   ownerModule: "workflow-engine",
@@ -1688,16 +1786,28 @@ var UPDATE_WORKTREE_TARGETS = {
 };
 var UPDATE_WORKTREE_METADATA = {
   name: "update_worktree_metadata",
-  description: "Update worktree sequencing metadata \u2014 execution order, dependencies, blocking relations, and gates. Like `git config` for a worktree \u2014 sets the scheduling and dependency metadata that determines when this worktree can activate relative to others. Use to backfill or correct sequencing data.",
+  description: "Update worktree sequencing metadata \u2014 campaign, lane, dependencies, blocking relations, and gates. Like `git config` for a worktree \u2014 sets the scheduling and dependency metadata that determines when this worktree can activate relative to others. Use to backfill or correct sequencing data.",
   parameters: {
     worktreeId: { type: "string", description: "The worktree to update" },
     hypothesis: {
       type: "string",
       description: "Testable claim this worktree investigates"
     },
-    executionOrder: {
+    campaign: {
+      type: "number",
+      description: "Top-level pipeline campaign number."
+    },
+    lane: {
+      type: "string",
+      description: "GitButler-aligned workstream lane name inside the campaign."
+    },
+    laneOrderInCampaign: {
       type: "number",
-      description: "Global execution order (1 = first, higher = later)"
+      description: "Ordering for this lane within the campaign."
+    },
+    orderInLane: {
+      type: "number",
+      description: "Position of this worktree inside its lane."
     },
     dependsOn: {
       type: "array",
@@ -1735,18 +1845,6 @@ var UPDATE_WORKTREE_METADATA = {
       type: "object",
       description: "Calibrated auto-fix policy controlling dry-run vs safe execution, per-run action caps, and permitted mutation tiers."
     },
-    track: {
-      type: "string",
-      description: "Parallel workstream name (e.g., 'ontology', 'tc-scope', 'control-plane', 'dev-portal', 'mcp-sdk-parity', 'execution-program'). Groups worktrees into named lanes for pipeline visualization and PM analysis."
-    },
-    trackPosition: {
-      type: "number",
-      description: "Position within the track (1-indexed). E.g., TC-A=1, TC-B=2, TC-C=3 within the 'tc-scope' track."
-    },
-    executionBand: {
-      type: "number",
-      description: "Parallel execution band number. All worktrees in the same band can run simultaneously. Band 2 = OE-B + TC-A, Band 3 = TC-B + 11D-R + S2-13A, etc."
-    },
     status: {
       type: "string",
       description: "Override the worktree status. Use for lifecycle transitions like marking a worktree superseded, long-term, or as a raw idea.",
@@ -2116,6 +2214,10 @@ var LIST_TASKS = {
       type: "string",
       description: "Filter to tasks linked to this worktree"
     },
+    worktreeId: {
+      type: "string",
+      description: "Alias for linkedWorktreeId"
+    },
     status: {
       type: "string",
       description: "Filter by status: todo, in_progress, blocked, done",
@@ -2203,7 +2305,7 @@ var GET_TOPIC = {
       description: "Legacy alias for topicId"
     }
   },
-  required: [],
+  required: ["topicId"],
   response: {
     description: "Single topic record",
     fields: {
@@ -2558,7 +2660,7 @@ var GET_ONTOLOGY = {
       description: "Tenant scope for key lookup. Omit for platform-level."
     }
   },
-  required: [],
+  required: ["id"],
   response: {
     description: "Ontology definition with latest published version",
     fields: {
@@ -2625,7 +2727,7 @@ var MATCH_ENTITY_TYPE = {
       description: "Optional maximum number of ranked matches to return"
     }
   },
-  required: ["text"],
+  required: ["text", "ontologyId"],
   response: {
     description: "Ranked ontology entity type matches",
     fields: {
@@ -2879,7 +2981,7 @@ var RECORD_SCOPE_LEARNING = {
 };
 var PIPELINE_SNAPSHOT = {
   name: "pipeline_snapshot",
-  description: "Summarize a topic's worktree pipeline in band-and-lane form. Like `git status --short` for Lucern execution \u2014 returns the hinge worktree, next planned wave, blockers, critical path, superseded work, and graph hygiene debt.",
+  description: "Summarize a topic's worktree pipeline in campaign-and-lane form. Like `git status --short` for Lucern execution \u2014 returns the hinge worktree, next planned wave, blockers, critical path, superseded work, and graph hygiene debt.",
   parameters: {
     topicId: { type: "string", description: "Topic scope ID" }
   },
@@ -2889,14 +2991,14 @@ var PIPELINE_SNAPSHOT = {
     fields: {
       topicId: "string",
       topicName: "string",
-      currentBand: "number | null",
-      nextBand: "number | null",
+      currentCampaign: "number | null",
+      nextCampaign: "number | null",
       activeWorktrees: "array \u2014 current hinge worktree(s)",
-      nextWave: "array \u2014 worktrees in the next planned band",
+      nextWave: "array \u2014 worktrees in the next planned campaign",
       readyNow: "array \u2014 planning worktrees with dependencies completed",
       blockedBy: "array \u2014 grouped blockers",
       criticalPath: "array \u2014 ordered incomplete worktree chain",
-      bands: "array \u2014 incomplete worktrees grouped by executionBand",
+      campaigns: "array \u2014 incomplete worktrees grouped by campaign",
       superseded: "array \u2014 worktrees marked superseded or not for activation",
       graphHygiene: "object \u2014 untargeted and taskless worktree debt",
       riskQuestions: "array \u2014 critical/high open questions",
@@ -3485,6 +3587,7 @@ var MCP_TOOL_CONTRACTS = {
   list_beliefs: LIST_BELIEFS,
   list_worktrees: LIST_WORKTREES,
   list_all_worktrees: LIST_ALL_WORKTREES,
+  list_campaigns: LIST_CAMPAIGNS,
   activate_worktree: ACTIVATE_WORKTREE,
   update_worktree_targets: UPDATE_WORKTREE_TARGETS,
   update_worktree_metadata: UPDATE_WORKTREE_METADATA,