@lucern/contracts 0.3.0-alpha.3 → 0.3.0-alpha.5

package/dist/function-registry/worktrees.js

@@ -422,6 +422,14 @@ var 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.",
   parameters: {
     title: { type: "string", description: "Worktree name/objective" },
+    name: {
+      type: "string",
+      description: "Optional storage-name alias for callers that already use backend naming"
+    },
+    projectId: {
+      type: "string",
+      description: "Legacy topicId alias"
+    },
     topicId: { type: "string", description: "Optional topic scope hint" },
     branchId: {
       type: "string",
@@ -435,14 +443,87 @@ var ADD_WORKTREE = {
       type: "string",
       description: "The testable claim this worktree investigates"
     },
+    rationale: {
+      type: "string",
+      description: "Why this worktree exists and why it belongs in the campaign"
+    },
+    worktreeType: {
+      type: "string",
+      description: "Schema-enum worktree type used by the kernel lifecycle and retrieval layers"
+    },
+    gate: {
+      type: "string",
+      description: "Exit gate name for this worktree"
+    },
+    startDate: {
+      type: "number",
+      description: "Planned start timestamp in milliseconds since epoch"
+    },
+    endDate: {
+      type: "number",
+      description: "Planned end timestamp in milliseconds since epoch"
+    },
+    durationWeeks: {
+      type: "number",
+      description: "Planned duration in weeks"
+    },
+    confidenceImpact: {
+      type: "string",
+      description: "Expected confidence impact if the worktree succeeds",
+      enum: ["high", "medium", "low"]
+    },
+    beliefFocus: {
+      type: "string",
+      description: "Natural-language focus spanning the target belief neighborhood"
+    },
     beliefIds: {
       type: "array",
-      description: "Beliefs to test in this worktree"
+      description: "Legacy alias for targetBeliefIds"
+    },
+    beliefs: {
+      type: "array",
+      description: "Legacy alias for targetBeliefIds"
+    },
+    targetBeliefIds: {
+      type: "array",
+      description: "Belief node IDs this worktree is expected to test or update"
+    },
+    targetQuestionIds: {
+      type: "array",
+      description: "Question node IDs this worktree is expected to answer"
+    },
+    keyQuestions: {
+      type: "array",
+      description: "Inline key question objects with question, optional status, answer, answerConfidence, and linkedQuestionId"
+    },
+    evidenceSignals: {
+      type: "array",
+      description: "Evidence signal objects with signal, optional collected state, progress, and notes"
+    },
+    decisionGate: {
+      type: "object",
+      description: "Decision gate object with goCriteria, noGoSignals, optional verdict, rationale, decidedAt, and decidedBy"
+    },
+    goCriteria: {
+      type: "array",
+      description: "Shorthand go criteria used to build decisionGate"
+    },
+    noGoSignals: {
+      type: "array",
+      description: "Shorthand no-go signals used to build decisionGate"
+    },
+    proofArtifacts: {
+      type: "array",
+      description: "Expected proof artifacts required to close the worktree"
     },
     autoShape: {
       type: "boolean",
       description: "Whether to invoke inquiry auto-shaping during worktree creation"
     },
+    autoFixPolicy: {
+      type: "object",
+      description: "Policy for permitted automatic remediation inside the worktree"
+    },
     domainPackId: {
       type: "string",
       description: "Optional domain pack whose shaping hooks should influence generated questions and tasks"
@@ -471,9 +552,17 @@ var ADD_WORKTREE = {
       type: "array",
       description: "Worktree IDs blocked by this worktree"
     },
-    gate: {
+    staffingHint: {
       type: "string",
-      description: "Exit gate name for this worktree"
+      description: "Suggested staffing or agent allocation note"
+    },
+    lensId: {
+      type: "string",
+      description: "Lens that scopes this worktree when applicable"
+    },
+    lastReconciledAt: {
+      type: "number",
+      description: "Timestamp when worktree metadata was last reconciled"
     }
   },
   required: ["title", "topicId"],
@@ -503,7 +592,7 @@ var MERGE = {
     worktreeId: { type: "string", description: "The worktree to merge" },
     outcomes: {
       type: "array",
-      description: "Scoring outcomes for each belief: { beliefId, confidence, rationale }"
+      description: "Merge outcomes as key-finding strings, or scoring outcomes for beliefs: { beliefId, confidence, rationale }"
     },
     summary: { type: "string", description: "Overall findings summary" }
   },
@@ -1057,6 +1146,74 @@ var GET_GRAPH_STRUCTURE_ANALYSIS = {
   ontologyPrimitive: "graph",
   tier: "showcase"
 };
+var LIST_GRAPH_INTELLIGENCE_QUERIES = {
+  name: "list_graph_intelligence_queries",
+  description: "List the Graph Intelligence query catalog that powers structural graph analysis experiences. Returns categories, query IDs, prompt templates, modes, and the public tool plan each query can use.",
+  parameters: {
+    categoryId: {
+      type: "string",
+      description: "Optional category filter, such as problems or strategic"
+    },
+    mode: {
+      type: "string",
+      description: "Optional mode filter: core, bias, stress, operational, alpha, semantic, or evidence"
+    }
+  },
+  required: [],
+  response: {
+    description: "Graph Intelligence query catalog and mode-to-tool mapping",
+    fields: {
+      categories: "array \u2014 query categories",
+      queries: "array \u2014 query definitions with prompt templates and tools",
+      quickQueries: "array \u2014 recommended one-click query presets",
+      publicToolNamesByMode: "object \u2014 public tool names available to each Graph Intelligence mode"
+    }
+  },
+  ownerModule: "graph-intelligence",
+  ontologyPrimitive: "graph",
+  tier: "showcase"
+};
+var RUN_GRAPH_INTELLIGENCE_QUERY = {
+  name: "run_graph_intelligence_query",
+  description: "Run a named Graph Intelligence query against a tenant topic graph. Returns the selected query, prompt, deterministic graph-analysis bundle, graph context, and public tool plan for model synthesis.",
+  parameters: {
+    topicId: { type: "string", description: "Topic to analyze" },
+    queryId: {
+      type: "string",
+      description: "Graph Intelligence query ID, such as confirmation-bias, pre-mortem, or thesis-summary"
+    },
+    prompt: {
+      type: "string",
+      description: "Optional custom prompt for custom analysis runs"
+    },
+    input: {
+      type: "string",
+      description: "Optional entity, theme, belief, company, or search text for input-driven queries"
+    },
+    mode: {
+      type: "string",
+      description: "Optional mode override: core, bias, stress, operational, alpha, semantic, or evidence"
+    },
+    limit: {
+      type: "number",
+      description: "Maximum graph context rows to return"
+    }
+  },
+  required: ["topicId"],
+  response: {
+    description: "Graph Intelligence query result bundle ready for model or prompt-library synthesis",
+    fields: {
+      query: "object \u2014 selected query definition",
+      prompt: "string \u2014 resolved prompt template",
+      toolPlan: "array \u2014 public tools and args the model can call next",
+      analysis: "object \u2014 structure, coverage, gap, and confirmation-bias analysis",
+      context: "object \u2014 sampled beliefs, questions, evidence, edges, and contradictions"
+    }
+  },
+  ownerModule: "graph-intelligence",
+  ontologyPrimitive: "graph",
+  tier: "showcase"
+};
 var GET_FALSIFICATION_QUESTIONS = {
   name: "get_falsification_questions",
   description: "Generate Popperian falsification questions for beliefs. Like `git test` \u2014 identifies the questions most likely to disprove current beliefs. Karl Popper as a tool: surfaces what would need to be true to invalidate each belief.",
@@ -3522,6 +3679,69 @@ var GENERATE_SESSION_HANDOFF = {
   tier: "showcase",
   internal: true
 };
+var BEGIN_BUILD_SESSION = {
+  name: "begin_build_session",
+  description: "Bootstrap a coding build session for a Lucern worktree. Like `git worktree add` plus `git status` \u2014 returns the compact context packet an agent needs before editing.",
+  parameters: {
+    worktreeId: {
+      type: "string",
+      description: "The Lucern worktree ID to bootstrap."
+    },
+    branch: {
+      type: "string",
+      description: "Optional git branch name. Auto-generated from the worktree name when omitted."
+    },
+    branchBase: {
+      type: "string",
+      description: 'Base branch for the feature branch. Default: "staging".'
+    },
+    prBase: {
+      type: "string",
+      description: 'Target branch for the PR. Default: "staging".'
+    },
+    sessionMode: {
+      type: "string",
+      description: 'Session mode: "async" for Codex/headless or "interactive" for live sessions.',
+      enum: ["async", "interactive"]
+    },
+    activateIfPlanning: {
+      type: "boolean",
+      description: "When true, automatically activate a planning worktree during bootstrap."
+    }
+  },
+  required: ["worktreeId"],
+  response: {
+    description: "A compact build-session packet with worktree metadata, graph anchors, questions, dependencies, and git defaults.",
+    fields: {
+      topicId: "string \u2014 canonical topic scope",
+      topicName: "string \u2014 human-readable topic name",
+      worktreeId: "string \u2014 worktree ID",
+      worktreeName: "string \u2014 human-readable worktree name",
+      branch: "string \u2014 git branch name",
+      branchBase: "string \u2014 base branch",
+      prBase: "string \u2014 PR target branch",
+      campaign: "number | null \u2014 top-level pipeline campaign",
+      lane: "string \u2014 campaign lane",
+      gate: "string \u2014 exit gate",
+      hypothesis: "string \u2014 worktree hypothesis",
+      focus: "string \u2014 session focus",
+      status: "string \u2014 worktree status after optional activation",
+      sessionMode: "string \u2014 async | interactive",
+      targetBeliefIds: "array \u2014 scoped belief IDs",
+      targetQuestionIds: "array \u2014 scoped question IDs",
+      topBeliefs: "array \u2014 highest-confidence scoped beliefs",
+      openQuestions: "array \u2014 open scoped questions",
+      resolvedDecisions: "array \u2014 answered questions summarized for the session",
+      dependencies: "array \u2014 upstream worktrees",
+      unblocks: "array \u2014 downstream worktrees",
+      mergeOrderNotes: "string \u2014 merge ordering advisory"
+    }
+  },
+  ownerModule: "bootstrap",
+  ontologyPrimitive: "worktree",
+  tier: "showcase",
+  internal: true
+};
 var MCP_TOOL_CONTRACTS = {
   // Belief lifecycle (commit, amend, fork, archive)
   create_belief: CREATE_BELIEF,
@@ -3569,6 +3789,8 @@ var MCP_TOOL_CONTRACTS = {
   // Graph intelligence (showcase)
   detect_confirmation_bias: DETECT_CONFIRMATION_BIAS,
   get_graph_structure_analysis: GET_GRAPH_STRUCTURE_ANALYSIS,
+  list_graph_intelligence_queries: LIST_GRAPH_INTELLIGENCE_QUERIES,
+  run_graph_intelligence_query: RUN_GRAPH_INTELLIGENCE_QUERY,
   get_falsification_questions: GET_FALSIFICATION_QUESTIONS,
   // Evidence operations (workhorse)
   search_evidence: SEARCH_EVIDENCE,
@@ -3615,6 +3837,7 @@ var MCP_TOOL_CONTRACTS = {
   get_agent_inbox: GET_AGENT_INBOX,
   claim_files: CLAIM_FILES,
   generate_session_handoff: GENERATE_SESSION_HANDOFF,
+  begin_build_session: BEGIN_BUILD_SESSION,
   // Policy / ACL (workhorse)
   check_permission: CHECK_PERMISSION,
   filter_by_permission: FILTER_BY_PERMISSION,
@@ -3750,6 +3973,8 @@ var MCP_ANALYSIS_PLATFORM_OPERATION_NAMES = [
   "traverse_graph",
   "get_graph_neighborhood",
   "get_graph_structure_analysis",
+  "list_graph_intelligence_queries",
+  "run_graph_intelligence_query",
   "find_contradictions",
   "flag_contradiction",
   "detect_confirmation_bias",
@@ -3828,6 +4053,7 @@ var PLATFORM_INTERNAL_OPERATION_NAMES = [
   "get_change_history",
   "get_failure_log",
   "record_attempt",
+  "begin_build_session",
   "push",
   "open_pull_request",
   "record_judgment",
@@ -3882,7 +4108,6 @@ var SDK_ONLY_OPERATION_NAMES = [
   "find_semantic_orphans"
 ];
 var MCP_ONLY_INTERNAL_OPERATION_NAMES = [
-  "begin_build_session",
   "evaluate_engineering_contract",
   "evaluate_research_contract"
 ];
@@ -4249,8 +4474,76 @@ function surfaceContract(args) {
     }
   });
 }
-
-// src/function-registry/worktrees.ts
+var autoFixPolicyInputSchema = z.object({
+  enabled: z.boolean().optional().describe("Whether automatic remediation is enabled."),
+  mode: z.string().optional().describe("Automation mode for worktree auto-fixes."),
+  maxAttempts: z.number().optional().describe("Maximum number of auto-fix attempts."),
+  reviewer: z.string().optional().describe("Reviewer responsible for auto-fix oversight."),
+  maxActionsPerRun: z.number().optional().describe("Maximum number of auto-fix actions per run."),
+  permittedMutationTiers: z.array(z.enum(["read_only", "low_risk_write", "high_risk_write"])).optional().describe("Mutation tiers the auto-fix worker may execute."),
+  requireAuditTrail: z.boolean().optional().describe("Whether auto-fix actions must write an audit trail."),
+  escalationGate: z.string().optional().describe("Gate to trigger when auto-fix policy requires escalation.")
+}).passthrough().describe("Policy for permitted automatic remediation inside the worktree.");
+var worktreeKeyQuestionInputSchema = z.object({
+  question: z.string().describe("Question the worktree must resolve."),
+  status: z.enum(["open", "answered", "forked"]).optional().describe("Current disposition of the key question."),
+  answer: z.string().optional().describe("Captured answer when the key question is resolved."),
+  answerConfidence: z.enum(["high", "medium", "low"]).optional().describe("Confidence in the captured answer."),
+  linkedQuestionId: z.string().optional().describe("Canonical question node linked to this key question.")
+}).passthrough().describe("Question contract embedded in the worktree plan.");
+var worktreeEvidenceSignalInputSchema = z.object({
+  signal: z.string().describe("Evidence signal the worktree should collect."),
+  collected: z.boolean().optional().describe("Whether the signal has already been collected."),
+  progress: z.string().optional().describe("Collection progress note for the signal."),
+  notes: z.string().optional().describe("Additional evidence collection notes.")
+}).passthrough().describe("Evidence signal embedded in the worktree plan.");
+var worktreeDecisionGateInputSchema = z.object({
+  goCriteria: z.array(z.string()).describe("Criteria that must hold for the worktree to proceed."),
+  noGoSignals: z.array(z.string()).describe("Signals that stop or redirect the worktree."),
+  verdict: z.enum(["go", "no_go", "pivot", "pending"]).optional().describe("Current decision verdict for the worktree gate."),
+  verdictRationale: z.string().optional().describe("Rationale supporting the current gate verdict."),
+  decidedAt: z.number().optional().describe("Timestamp when the gate verdict was decided."),
+  decidedBy: z.string().optional().describe("Actor that decided the gate verdict.")
+}).passthrough().describe("Decision gate contract for worktree activation or exit.");
+var addWorktreeArgs = z.object({
+  title: z.string().optional().describe("Human-readable worktree name or objective."),
+  name: z.string().optional().describe("Storage-name alias for callers that already use backend naming."),
+  topicId: z.string().describe("Primary topic scope for the worktree."),
+  projectId: z.string().optional().describe("Legacy topicId alias."),
+  branchId: z.string().optional().describe("Legacy branch identifier for compatibility with workflow callers."),
+  objective: z.string().optional().describe("Reasoning objective this worktree is intended to resolve."),
+  hypothesis: z.string().optional().describe("Testable claim this worktree investigates."),
+  rationale: z.string().optional().describe("Why this worktree exists and why it belongs in the campaign."),
+  worktreeType: z.string().optional().describe("Schema-enum worktree type used for kernel lifecycle behavior."),
+  gate: z.string().optional().describe("Exit gate for this worktree."),
+  startDate: z.number().optional().describe("Planned start timestamp in milliseconds since epoch."),
+  endDate: z.number().optional().describe("Planned end timestamp in milliseconds since epoch."),
+  durationWeeks: z.number().optional().describe("Planned duration in weeks."),
+  confidenceImpact: z.enum(["high", "medium", "low"]).optional().describe("Expected confidence impact if this worktree succeeds."),
+  beliefFocus: z.string().optional().describe("Natural-language focus spanning the target belief neighborhood."),
+  beliefIds: z.array(z.string()).optional().describe("Legacy alias for targetBeliefIds."),
+  beliefs: z.array(z.string()).optional().describe("Legacy alias for targetBeliefIds."),
+  targetBeliefIds: z.array(z.string()).optional().describe("Belief node IDs this worktree is expected to test or update."),
+  targetQuestionIds: z.array(z.string()).optional().describe("Question node IDs this worktree is expected to answer."),
+  keyQuestions: z.array(worktreeKeyQuestionInputSchema).optional().describe("Inline key questions captured as part of the worktree plan."),
+  evidenceSignals: z.array(worktreeEvidenceSignalInputSchema).optional().describe("Evidence signals the worktree needs to collect or validate."),
+  decisionGate: worktreeDecisionGateInputSchema.optional(),
+  goCriteria: z.array(z.string()).optional().describe("Shorthand go criteria used to build decisionGate."),
+  noGoSignals: z.array(z.string()).optional().describe("Shorthand no-go signals used to build decisionGate."),
+  proofArtifacts: z.array(z.unknown()).optional().describe("Expected proof artifacts required to close the worktree."),
+  autoShape: z.boolean().optional().describe("Whether to invoke inquiry auto-shaping during creation."),
+  autoFixPolicy: autoFixPolicyInputSchema.optional(),
+  domainPackId: z.string().optional().describe("Domain pack whose shaping hooks should influence the worktree."),
+  campaign: z.number().optional().describe("Top-level pipeline campaign number."),
+  lane: z.string().optional().describe("Campaign lane for the worktree."),
+  laneOrderInCampaign: z.number().optional().describe("Ordering for this lane within its campaign."),
+  orderInLane: z.number().optional().describe("Position of this worktree inside its lane."),
+  dependsOn: z.array(z.string()).optional().describe("Worktree IDs that must complete before this worktree."),
+  blocks: z.array(z.string()).optional().describe("Worktree IDs blocked by this worktree."),
+  staffingHint: z.string().optional().describe("Suggested staffing or agent allocation note."),
+  lensId: z.string().optional().describe("Lens that scopes this worktree when applicable."),
+  lastReconciledAt: z.number().optional().describe("Timestamp when worktree metadata was last reconciled.")
+});
 var worktreeIdInput = (input) => compactRecord({
   worktreeId: input.worktreeId ?? input.id
 });
@@ -4283,6 +4576,50 @@ var worktreeMetadataInput = (input) => compactRecord({
   autoFixPolicy: input.autoFixPolicy,
   lastReconciledAt: input.lastReconciledAt
 });
+var worktreeMetadataArgs = z.object({
+  worktreeId: z.string().describe("The worktree to update."),
+  id: z.string().optional().describe("Worktree ID alias."),
+  topicId: z.string().optional().describe("Primary topic scope."),
+  additionalTopicIds: z.array(z.string()).optional().describe("Additional topic scopes associated with this worktree."),
+  status: z.string().optional().describe("Worktree lifecycle status."),
+  campaign: z.number().optional().describe("Top-level pipeline campaign."),
+  lane: z.string().optional().describe("Campaign lane."),
+  laneOrderInCampaign: z.number().optional().describe("Ordering for this lane within its campaign."),
+  orderInLane: z.number().optional().describe("Position of this worktree inside its lane."),
+  gate: z.string().optional().describe("Exit gate for this worktree."),
+  hypothesis: z.string().optional().describe("Testable claim this worktree investigates."),
+  objective: z.string().optional().describe("Reasoning objective for the worktree."),
+  rationale: z.string().optional().describe("Why this worktree is sequenced here."),
+  proofArtifacts: z.array(z.unknown()).optional().describe("Proof artifacts required to close the worktree."),
+  staffingHint: z.string().optional().describe("Suggested staffing or agent allocation note."),
+  blocks: z.array(z.string()).optional().describe("Worktree IDs blocked by this worktree."),
+  dependsOn: z.array(z.string()).optional().describe("Worktree IDs this worktree depends on."),
+  lensId: z.string().optional().describe("Lens that scopes this worktree."),
+  autoFixPolicy: autoFixPolicyInputSchema.optional(),
+  lastReconciledAt: z.number().optional().describe("Timestamp of the last deterministic reconciliation pass.")
+});
+var pushArgs = worktreeMetadataArgs.extend({
+  targetContext: z.string().describe("Where to push merged findings."),
+  beliefIds: z.array(z.string()).optional().describe("Optional subset of beliefs to push.")
+});
+var openPullRequestArgs = worktreeMetadataArgs.extend({
+  reviewers: z.array(z.string()).optional().describe("User IDs of requested reviewers."),
+  summary: z.string().describe("Summary of findings and why they are ready for review.")
+});
+var mergeKeyFindingsInput = (input) => {
+  if (Array.isArray(input.keyFindings)) {
+    return input.keyFindings;
+  }
+  if (Array.isArray(input.outcomes)) {
+    const findings = input.outcomes.filter(
+      (outcome) => typeof outcome === "string" && outcome.trim().length > 0
+    );
+    if (findings.length > 0) {
+      return findings;
+    }
+  }
+  return [input.summary ?? "Merged worktree"];
+};
 var listAllWorktreesInput = (input) => compactRecord({
   status: input.status,
   lane: input.lane,
@@ -4290,6 +4627,16 @@ var listAllWorktreesInput = (input) => compactRecord({
   limit: input.limit
 });
 var worktreesContracts = [
+  surfaceContract({
+    name: "begin_build_session",
+    kind: "mutation",
+    domain: "worktrees",
+    surfaceClass: "platform_internal",
+    path: "/mcp/build-session/begin",
+    sdkNamespace: "worktrees",
+    sdkMethod: "beginBuildSession",
+    summary: "Begin a coding build session for a worktree."
+  }),
   surfaceContract({
     name: "add_worktree",
     kind: "mutation",
@@ -4306,13 +4653,12 @@ var worktreesContracts = [
       inputProjection: (input, context) => withCreatedBy(
         compactRecord({
           name: input.name ?? input.title,
-          topicId: input.topicId,
+          topicId: input.topicId ?? input.projectId,
           worktreeType: input.worktreeType,
           objective: input.objective,
           gate: input.gate,
           hypothesis: input.hypothesis,
           rationale: input.rationale,
-          signal: input.signal,
           startDate: input.startDate,
           endDate: input.endDate,
           durationWeeks: input.durationWeeks,
@@ -4338,12 +4684,12 @@ var worktreesContracts = [
           staffingHint: input.staffingHint,
           domainPackId: input.domainPackId,
           lensId: input.lensId,
-          linkedQuestionId: input.linkedQuestionId,
           lastReconciledAt: input.lastReconciledAt
         }),
         context
       )
-    }
+    },
+    args: addWorktreeArgs
   }),
   surfaceContract({
     name: "activate_worktree",
@@ -4455,7 +4801,8 @@ var worktreesContracts = [
       functionName: "updateMetadata",
       kind: "mutation",
       inputProjection: worktreeMetadataInput
-    }
+    },
+    args: worktreeMetadataArgs
   }),
   surfaceContract({
     name: "merge",
@@ -4473,9 +4820,7 @@ var worktreesContracts = [
       inputProjection: (input, context) => withUserId(
         {
           ...worktreeIdInput(input),
-          keyFindings: input.keyFindings ?? [
-            input.summary ?? "Merged worktree"
-          ],
+          keyFindings: mergeKeyFindingsInput(input),
           decisionsReached: input.decisionsReached ?? [],
           nextSteps: input.nextSteps ?? []
         },
@@ -4497,7 +4842,8 @@ var worktreesContracts = [
       functionName: "updateMetadata",
       kind: "mutation",
       inputProjection: worktreeMetadataInput
-    }
+    },
+    args: pushArgs
   }),
   surfaceContract({
     name: "open_pull_request",
@@ -4513,7 +4859,8 @@ var worktreesContracts = [
       functionName: "updateMetadata",
       kind: "mutation",
       inputProjection: worktreeMetadataInput
-    }
+    },
+    args: openPullRequestArgs
   })
 ];