kibi-runtime 2.1.0 → 2.2.0

package/dist/index.js

@@ -19154,9 +19154,25 @@ function bootstrapEmptyKbSnapshotId(input) {
     sourceHashes: input.sourceHashes
   })).digest("hex")}`;
 }
-var BOOTSTRAP_PROVIDER_ORDER;
+var KNOWLEDGE_SOURCE_KINDS, KNOWLEDGE_SOURCE_AUTHORITIES, BOOTSTRAP_PROVIDER_ORDER;
 var init_types = __esm(() => {
   init_shared();
+  KNOWLEDGE_SOURCE_KINDS = [
+    "issue_tracker",
+    "wiki",
+    "specification",
+    "design",
+    "decision_log",
+    "support",
+    "chat",
+    "repository_docs",
+    "other"
+  ];
+  KNOWLEDGE_SOURCE_AUTHORITIES = [
+    "authoritative",
+    "supporting",
+    "stale"
+  ];
   BOOTSTRAP_PROVIDER_ORDER = [
     "typed_kibi_docs",
     "generic_repo_docs",
@@ -30977,6 +30993,8 @@ function parseTelemetryUsageLog(contents) {
     if (!isRecord9(parsed)) {
       throw new Error(`Failed to parse .kb/usage.log line ${index + 1}: expected object`);
     }
+    if (parsed.interface === "hook")
+      continue;
     events.push(parsed);
   }
   return events;
@@ -48479,7 +48497,7 @@ async function refreshUnlocked(symbolId, context, options2 = {}) {
   }
   const sourceFile = typeof entry.sourceFile === "string" ? entry.sourceFile : "";
   const title = typeof entry.title === "string" ? entry.title : "";
-  const [enriched] = await enrichSymbolCoordinates([{ ...entry, id: symbolId, title, sourceFile }], context.workspaceRoot);
+  const [enriched] = await enrichSymbolCoordinates([{ ...entry, id: symbolId, title, sourceFile }], context.workspaceRoot, { allowPythonDecoratorCoordinates: true });
   let next = coordinate(enriched);
   let sourceText = next === null ? sourceTextFor(sourceFile, context.workspaceRoot) : null;
   if (next === null && isCoarseGranularityReason(entry.granularity_reason) && sourceText !== null) {
@@ -53652,7 +53670,9 @@ async function inspectCoordinateRepairs(symbols, workspaceRoot) {
       ...typeof symbol.granularity_reason === "string" ? { granularity_reason: symbol.granularity_reason } : {}
     };
   });
-  const enriched = await enrichSymbolCoordinates(entries, workspaceRoot);
+  const enriched = await enrichSymbolCoordinates(entries, workspaceRoot, {
+    allowPythonDecoratorCoordinates: true
+  });
   return new Map(entries.map((entry, index) => {
     const sourceFile = entry.sourceFile ?? null;
     let source = null;
@@ -61883,12 +61903,94 @@ async function discoverBootstrap(context) {
   };
 }
 
+// ../cli/dist/operations/bootstrap/intent-claims.js
+var AUTHORITY_CONFIDENCE = {
+  authoritative: 0.9,
+  supporting: 0.82
+};
+function citation(source, claim) {
+  return [
+    `intent_claim:${source.id}:${claim.reference}`,
+    `knowledge_source:${source.kind}:${source.locator}`,
+    `source_authority:${source.authority}`,
+    ...source.connector ? [`connector:${source.connector}`] : []
+  ];
+}
+function buildIntentClaimCandidates(declared, existingIds, minConfidence) {
+  const sources = new Map((declared.knowledgeSources ?? []).map((source) => [source.id, source]));
+  const candidates = [];
+  const sourceOnlySignals = [];
+  const suppressed = [];
+  const diagnostics = [];
+  for (const claim of declared.intentClaims ?? []) {
+    const source = sources.get(claim.sourceId);
+    if (!source) {
+      diagnostics.push(`Intent claim cites an undeclared knowledge source "${claim.sourceId}" (${claim.reference}); declare it in knowledgeSources or drop the claim.`);
+      continue;
+    }
+    if (source.authority === "stale") {
+      suppressed.push({
+        candidateId: "",
+        reason: "stale_knowledge_source",
+        sourcePath: claim.reference,
+        entityType: "req",
+        statement: claim.statement,
+        sourceId: source.id
+      });
+      continue;
+    }
+    const confidence = AUTHORITY_CONFIDENCE[source.authority];
+    const evidence = citation(source, claim);
+    const provenance = `${source.id}:${claim.reference}`;
+    const modeled = claimFor(claim.statement, `knowledge-source:${source.id}`, confidence, provenance);
+    const writeSet = modeled ? buildStrictWriteSet({ claim: modeled, statement: claim.statement }) : null;
+    if (writeSet?.isStrict && confidence >= minConfidence && !existingIds.has(writeSet.req.id)) {
+      candidates.push({
+        candidateId: `claim:${source.id}:${writeSet.req.id.toLowerCase()}`,
+        entityType: "req",
+        title: claim.statement,
+        sourceKind: "intent_claim",
+        sourcePath: claim.reference,
+        confidence,
+        confidenceBand: confidenceBand(confidence),
+        evidence,
+        relationships: writeSet.relationships.map(({ type, from, to }) => ({
+          type,
+          from,
+          to
+        })),
+        applyPlan: strictPlan(writeSet)
+      });
+      continue;
+    }
+    if (writeSet?.isStrict && existingIds.has(writeSet.req.id)) {
+      suppressed.push({
+        candidateId: `claim:${source.id}:${writeSet.req.id.toLowerCase()}`,
+        reason: "entity_exists",
+        sourcePath: claim.reference,
+        entityType: "req"
+      });
+      continue;
+    }
+    sourceOnlySignals.push({
+      kind: "req",
+      title: `Author requirement from ${source.title} ${claim.reference}: ${claim.statement}`,
+      sourcePath: claim.reference,
+      confidence,
+      evidence
+    });
+  }
+  return { candidates, sourceOnlySignals, suppressed, diagnostics };
+}
+
 // ../cli/dist/operations/bootstrap/guidance.js
 import path26 from "node:path";
 
 // ../cli/dist/operations/bootstrap/guidance-actions.js
 import path25 from "node:path";
 function relative2(root, target) {
+  if (!path25.isAbsolute(target))
+    return target;
   const value = path25.relative(root, target);
   return value.startsWith("..") || path25.isAbsolute(value) ? target.split(path25.sep).join("/") : value.split(path25.sep).join("/");
 }
@@ -61958,6 +62060,8 @@ function buildActions(root, activation, declared, candidates, signals) {
 
 // ../cli/dist/operations/bootstrap/guidance.js
 function relative3(root, target) {
+  if (!path26.isAbsolute(target))
+    return target;
   const value = path26.relative(root, target);
   return value.startsWith("..") || path26.isAbsolute(value) ? target.split(path26.sep).join("/") : value.split(path26.sep).join("/");
 }
@@ -61979,6 +62083,8 @@ function prompt(root, activation, declared, candidates, signals, warnings) {
     bullets.push(`- Summary: ${declared.projectSummary}`);
   if (declared.sourceOfTruthPaths.length > 0)
     bullets.push(`- Source of truth: ${summary2(declared.sourceOfTruthPaths)}.`);
+  if (declared.knowledgeSources)
+    bullets.push(`- Knowledge sources: ${summary2(declared.knowledgeSources.map((source) => `${source.title} (${source.authority})`))}; ${declared.intentClaims?.length ?? 0} cited intent claim(s).`);
   if (candidates.length > 0) {
     const formatted = Object.entries(counts(candidates)).sort(([left], [right]) => left.localeCompare(right)).map(([type, count]) => `${type} ${count}`).join(", ");
     bullets.push(`- Safe candidates: ${candidates.length} (${formatted}).`);
@@ -62024,7 +62130,7 @@ function confidence(activation, declared, candidates, signals, promptBlock) {
     vendored_blocked: -0.25
   }[activation.activationMode];
   reasons.push(`${activation.activationMode} determined the bootstrap posture.`);
-  if (declared.projectSummary || declared.sourceOfTruthPaths.length + declared.sourceOfTruthNotes.length + declared.priorityRoots.length + declared.verificationAnchors.length > 0) {
+  if (declared.projectSummary || declared.sourceOfTruthPaths.length + declared.sourceOfTruthNotes.length + declared.priorityRoots.length + declared.verificationAnchors.length + (declared.knowledgeSources?.length ?? 0) > 0) {
     score += 0.08;
     reasons.push("Declared bootstrap context grounds the output.");
   } else
@@ -62065,14 +62171,65 @@ function strings(values) {
     ...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))
   ];
 }
+function knowledgeSources(values) {
+  const seen = new Set;
+  const result = [];
+  for (const value of values ?? []) {
+    const id = value.id?.trim();
+    const title = value.title?.trim();
+    const locator = value.locator?.trim();
+    if (!id || !title || !locator || seen.has(id) || !KNOWLEDGE_SOURCE_KINDS.includes(value.kind) || !KNOWLEDGE_SOURCE_AUTHORITIES.includes(value.authority))
+      continue;
+    seen.add(id);
+    const connector = value.connector?.trim();
+    const notes = value.notes?.trim();
+    result.push({
+      id,
+      kind: value.kind,
+      title,
+      locator,
+      authority: value.authority,
+      ...connector ? { connector } : {},
+      ...notes ? { notes } : {}
+    });
+  }
+  return result;
+}
+function intentClaims(values) {
+  const seen = new Set;
+  const result = [];
+  for (const value of values ?? []) {
+    const statement = value.statement?.trim().replace(/\s+/g, " ");
+    const sourceId = value.sourceId?.trim();
+    const reference = value.reference?.trim();
+    if (!statement || !sourceId || !reference)
+      continue;
+    const key = `${sourceId}\x00${reference}\x00${statement}`;
+    if (seen.has(key))
+      continue;
+    seen.add(key);
+    const excerpt = value.excerpt?.trim();
+    result.push({
+      statement,
+      sourceId,
+      reference,
+      ...excerpt ? { excerpt } : {}
+    });
+  }
+  return result;
+}
 function normalizeBootstrapContext(input) {
   const projectSummary = input?.projectSummary?.trim();
+  const sources = knowledgeSources(input?.knowledgeSources);
+  const claims = intentClaims(input?.intentClaims);
   return {
     ...projectSummary ? { projectSummary } : {},
     sourceOfTruthPaths: strings(input?.sourceOfTruthPaths),
     sourceOfTruthNotes: strings(input?.sourceOfTruthNotes),
     priorityRoots: strings(input?.priorityRoots),
-    verificationAnchors: strings(input?.verificationAnchors)
+    verificationAnchors: strings(input?.verificationAnchors),
+    ...sources.length > 0 ? { knowledgeSources: sources } : {},
+    ...claims.length > 0 ? { intentClaims: claims } : {}
   };
 }
 function payoff(candidates) {
@@ -62124,6 +62281,8 @@ function presentBootstrap(input) {
   if (status === "needs_context") {
     if (!declaredContext.projectSummary)
       contextQuestions.push("What is the one-sentence purpose of this repository?");
+    if (!declaredContext.knowledgeSources)
+      contextQuestions.push("Which knowledge sources outside the code (issue trackers, wikis, specs, decision logs) describe product intent, and which of them are authoritative?");
     if (declaredContext.sourceOfTruthPaths.length === 0)
       contextQuestions.push("Which repository paths are authoritative for product intent?");
     if (input.sourceOnlySignals.length > 0)
@@ -62136,7 +62295,8 @@ function presentBootstrap(input) {
   const diagnostics = [
     ...input.migrationWarning ? [input.migrationWarning] : [],
     ...input.discoverySummary.scanWarnings,
-    ...bindingDiagnostics
+    ...bindingDiagnostics,
+    ...strings(input.contextDiagnostics)
   ];
   const planBody = {
     version: "kibi.bootstrap-plan.v1",
@@ -62328,8 +62488,14 @@ async function executePlanBootstrap(args, context) {
   ]);
   const bound = await expectedSnapshots(context, discovery.evidence.map((evidence) => evidence.relativePath).filter((value) => Boolean(value)));
   const built = discovery.activation.allowCandidateGeneration ? buildBootstrapCandidates(discovery.evidence, existingIds, minConfidence, includeGenericMarkdown) : { candidates: [], sourceOnlySignals: [] };
-  const filteredSignals = filterSourceOnlySignals(built.sourceOnlySignals, args.entityTypes);
-  const selected = selectBootstrapCandidates(built.candidates.filter((candidate) => candidate.confidence >= minConfidence), existingIds, args.entityTypes, maxCandidates);
+  const claimed = discovery.activation.allowCandidateGeneration ? buildIntentClaimCandidates(normalizeBootstrapContext(args.bootstrapContext), existingIds, minConfidence) : {
+    candidates: [],
+    sourceOnlySignals: [],
+    suppressed: [],
+    diagnostics: []
+  };
+  const filteredSignals = filterSourceOnlySignals([...built.sourceOnlySignals, ...claimed.sourceOnlySignals], args.entityTypes);
+  const selected = selectBootstrapCandidates([...built.candidates, ...claimed.candidates].filter((candidate) => candidate.confidence >= minConfidence), existingIds, args.entityTypes, maxCandidates);
   const ignored = discovery.ignoredSources.map((sourcePath) => ({
     candidateId: "",
     reason: "ignored_source",
@@ -62345,17 +62511,23 @@ async function executePlanBootstrap(args, context) {
     ...args.bootstrapContext ? { bootstrapContext: args.bootstrapContext } : {},
     candidates: selected.candidates,
     sourceOnlySignals: filteredSignals,
-    suppressedCandidates: [...selected.suppressed, ...ignored],
+    suppressedCandidates: [
+      ...selected.suppressed,
+      ...claimed.suppressed,
+      ...ignored
+    ],
     expected,
-    bindingDiagnostics
+    bindingDiagnostics,
+    contextDiagnostics: claimed.diagnostics
   });
 }
 
 // ../cli/dist/public/operations/specs/bootstrap.js
+init_types();
 var planBootstrapSpec = {
   name: "kb_plan_bootstrap",
   cliName: "plan-bootstrap",
-  description: "Generate a deterministic, snapshot-bound kibi.bootstrap-plan.v1 for repository onboarding. Read-only analysis returns evidence, bounded context questions, exact dependency-ordered actions, a canonical plan hash, and no mutation side effects.",
+  description: "Generate a deterministic, snapshot-bound kibi.bootstrap-plan.v1 for repository onboarding. Read-only analysis of the repository plus any declared knowledge sources and cited intent claims returns evidence, bounded context questions, exact dependency-ordered actions, a canonical plan hash, and no mutation side effects.",
   businessInputSchema: {
     type: "object",
     properties: {
@@ -62413,6 +62585,70 @@ var planBootstrapSpec = {
             type: "array",
             items: { type: "string" },
             description: "Optional verification commands, documents, or checkpoints to reference in the output."
+          },
+          knowledgeSources: {
+            type: "array",
+            maxItems: 50,
+            description: "Knowledge sources outside the code that the human confirmed during the bootstrap interview (issue trackers, wikis, specs, decision logs). Kibi never contacts them; the agent reads them through its own connectors and cites them from intentClaims. Bound into the plan hash.",
+            items: {
+              type: "object",
+              required: ["id", "kind", "title", "locator", "authority"],
+              additionalProperties: false,
+              properties: {
+                id: {
+                  type: "string",
+                  pattern: "^[a-z0-9][a-z0-9-]*$",
+                  description: "Stable kebab-case handle that intentClaims cite, for example jira-payments."
+                },
+                kind: { type: "string", enum: [...KNOWLEDGE_SOURCE_KINDS] },
+                title: { type: "string", minLength: 1 },
+                locator: {
+                  type: "string",
+                  minLength: 1,
+                  description: "Where the source lives: a URL, project key, space name, or repo-relative path."
+                },
+                authority: {
+                  type: "string",
+                  enum: [...KNOWLEDGE_SOURCE_AUTHORITIES],
+                  description: "The human's call: authoritative claims become higher-confidence candidates, supporting claims lower ones, and stale sources are cited but never produce candidates."
+                },
+                connector: {
+                  type: "string",
+                  description: "Optional name of the MCP server or tool the agent used to read the source."
+                },
+                notes: { type: "string" }
+              }
+            }
+          },
+          intentClaims: {
+            type: "array",
+            maxItems: 200,
+            description: "Statements of product intent the agent harvested from knowledgeSources, each citing its source. Normative claims the strict modeler can ground become cited req candidates; the rest become explicit authoring follow-ups. Bound into the plan hash.",
+            items: {
+              type: "object",
+              required: ["statement", "sourceId", "reference"],
+              additionalProperties: false,
+              properties: {
+                statement: {
+                  type: "string",
+                  minLength: 1,
+                  description: "One normative statement in the source's meaning, for example 'Refunds must not exceed the original charge.'"
+                },
+                sourceId: {
+                  type: "string",
+                  description: "The id of a declared knowledge source."
+                },
+                reference: {
+                  type: "string",
+                  minLength: 1,
+                  description: "Exact citation inside the source: a ticket key, page URL, or section anchor."
+                },
+                excerpt: {
+                  type: "string",
+                  description: "Optional short quote supporting the claim."
+                }
+              }
+            }
           }
         }
       }

package/dist/skills/kibi-bootstrap/SKILL.md

@@ -1,8 +1,8 @@
 ---
 id: kibi-bootstrap
 name: kibi-bootstrap
-description: Bootstrap Kibi from the current Git checkout with exact Git attachment, preview approval, source-first writes, and repair-safe completion.
-version: 3.0.0
+description: Bootstrap Kibi from the current Git checkout and the project's existing knowledge sources, with a source interview, cited intent claims, preview approval, source-first writes, and repair-safe completion.
+version: 3.1.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -18,20 +18,56 @@ resources:
 ## Goal
 
 Seed branch-local Kibi knowledge for an attached but thin repository without
-creating a parallel human-maintained ticket system. Ask at most four bounded
-context questions only when the planner says repository evidence is
-insufficient; agents own deterministic translation and humans resolve genuine
-ambiguity. A seeded repository hands off to the normal Kibi workflow.
+creating a parallel human-maintained ticket system. Code shows what the
+system does, not why; intent usually lives elsewhere (issue trackers, wikis,
+specs, decision logs). Lead a short interview to find those sources, harvest
+cited intent from them, and let the planner consolidate it with repository
+evidence. Agents own reading and translation; humans name the sources,
+judge their authority, and resolve genuine ambiguity. A seeded repository
+hands off to the normal Kibi workflow.
 
 ## Interface and preview
 
 Use the visible approved MCP surface or the trusted project-local CLI as equal
-peer interfaces. If neither is available, stop. Run `kb_plan_bootstrap` (or
-`plan-bootstrap --input`) read-only. If it returns `needs_context`, ask only its
+peer interfaces. If neither is available, stop. Interview first, then plan,
+then preview the exact plan for approval.
+
+## Interview first
+
+Before planning:
+
+1. Inventory what you can already read: your own MCP connectors and tools
+   (issue trackers such as Jira, YouTrack, Linear, or GitHub Issues; wikis such
+   as Confluence or Notion; drives and design tools), and in-repo docs, ADRs,
+   and specs.
+2. Ask the human, in one message: what the repository is for; which of those
+   sources hold product intent; which are authoritative, supporting, or stale;
+   what is missing; and which product areas matter first. If an important
+   source has no connector, say which one and suggest connecting it, then
+   continue with what is reachable. Never invent access you lack.
+3. Read the confirmed, non-stale sources through your connectors. Harvest one
+   normative statement per behavior, each citing its source and an exact
+   reference (ticket key, page URL, or section anchor). Keep the source's
+   meaning; do not merge, generalize, or resolve conflicts yourself.
+
+Declare the result in `bootstrapContext`: `projectSummary`,
+`knowledgeSources` (id, kind, title, locator, authority, optional connector),
+and `intentClaims` (statement, sourceId, reference, optional excerpt). Kibi
+never contacts those sources; it binds what you declare into the plan hash.
+
+## Plan and approval
+
+Run `kb_plan_bootstrap` (or `plan-bootstrap --input`) read-only with that
+context. Grounded authoritative or supporting claims become cited `req`
+candidates; claims the strict modeler cannot ground come back as authoring
+follow-ups; stale sources produce no candidates; undeclared sources are
+reported in diagnostics. If the plan returns `needs_context`, ask only its
 bounded questions (never more than four), then rerun the planner. Show the
-complete returned `structuredContent.plan`, including its canonical hash, and
-get explicit approval before any write. Pass that plan object unchanged to
-`kb_apply_plan`; do not reconstruct it from preview fields.
+complete returned `structuredContent.plan`, including its canonical hash and
+which candidates cite which sources, and get explicit approval before any
+write. Pass that plan object unchanged to `kb_apply_plan`; do not reconstruct
+it from preview fields. When a claim contradicts the code or another claim,
+put it to the human instead of choosing.
 
 For CLI JSON, use the trusted route with `--input` (for example
 `printf '%s\n' '{}' | kibi status --input -`); MCP and CLI are semantic peers.

package/dist/skills/kibi-bootstrap/resources/bootstrap.md

@@ -1,6 +1,11 @@
 # Bootstrap resource
 
-`kb_plan_bootstrap` is read-only and returns `kibi.bootstrap-plan.v1`. Review
+`kb_plan_bootstrap` is read-only and returns `kibi.bootstrap-plan.v1`. Declared
+`knowledgeSources` and cited `intentClaims` are part of `declaredContext` and
+therefore of the plan hash; a candidate built from a claim has `sourceKind:
+intent_claim` and evidence rows `intent_claim:<sourceId>:<reference>`,
+`knowledge_source:<kind>:<locator>`, and `source_authority:<authority>`. Its
+requirement keeps the citation as `text_ref: <sourceId>:<reference>`. Review
 candidate evidence, exact actions, dependencies, expected snapshots, source
 hashes, bounded questions, diagnostics, and the canonical `planHash` before
 approving. A preview does not authorize source edits. After approval, pass the

package/dist/skills/kibi-usage/SKILL.md

@@ -56,6 +56,20 @@ printf '%s\n' '{"query":"checkout","limit":10}' | npx --no-install kibi search -
 Read `resources/operation-access.md` for the route, result version, effects,
 mutability, and Prolog requirements of each operation.
 
+## Working in a git worktree or another directory
+
+Kibi MCP servers start in one project and answer from its knowledge base.
+Every Kibi MCP tool accepts `workspaceRoot`: when your working directory is not
+the project the server started in (a git worktree, a sibling checkout), pass
+your working directory as `workspaceRoot` on every call. Host plugins with
+pre-tool hooks add it for you. The server answers from that workspace when it
+is a worktree of the same repository or lies under the client's MCP roots.
+
+If a result carries a `workspace_mismatch` diagnostic, the answer came from a
+different workspace than the one you asked for; its `detail.reason` says why.
+Use the CLI from your working directory instead: `npx --no-install kibi ...`
+runs where you are and needs no `workspaceRoot`.
+
 ## Safe workflow
 
 1. Always discover before you mutate: start with `kb_search`, then exact-filter with `kb_query`. Use

package/dist/skills/kibi-usage/resources/operation-access.md

@@ -41,3 +41,7 @@ printf '%s\n' '{"query":"authentication","limit":10}' | npx --no-install kibi se
 `_diagnostic_telemetry` is adapter metadata, not business input. Never copy it
 into entity properties. On `committed_with_repairs`, follow typed required
 `nextActions` and do not retry the original mutation.
+
+`workspaceRoot` is an MCP-only routing argument naming the directory a call is
+about (see the kibi-usage skill). The CLI JSON routes do not accept it; they
+always run in the current directory.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-runtime",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Narrow first-party runtime contracts and adapters for Kibi operations.",
   "type": "module",
   "main": "./dist/index.js",