kibi-cli 2.3.0 → 2.4.0

package/dist/public/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/public/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/public/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/public/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/dist/public/telemetry-acceptance.d.ts

@@ -15,6 +15,14 @@ export declare const DEFAULT_TELEMETRY_ACCEPTANCE_POLICY: {
     readonly advisorMaxAgeSeconds: number;
     readonly repeatedMutationFailureThreshold: 3;
 };
+/**
+ * Parse Kibi operation events from `.kb/usage.log`.
+ *
+ * Host plugin hooks share the log and tag their rows `interface: "hook"`.
+ * Those rows describe agent activity around Kibi calls, not Kibi operations,
+ * so they are dropped here: otherwise a busy editing session would push every
+ * operation out of the bounded acceptance window.
+ */
 export declare function parseTelemetryUsageLog(contents: string): TelemetryUsageEvent[];
 export declare function thresholdStatus(actual: number | undefined, operator: ">=" | "<=" | "<", expected: number): TelemetryMetricStatus;
 export declare function analyzeTelemetryAcceptance(events: readonly TelemetryUsageEvent[], now?: Date, policy?: TelemetryAcceptancePolicy): TelemetryAcceptanceReport;

package/dist/public/telemetry-acceptance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry-acceptance.d.ts","sourceRoot":"","sources":["../../src/public/telemetry-acceptance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAEV,yBAAyB,EACzB,yBAAyB,EAGzB,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,iCAAiC,CAAC;AAEzC,YAAY,EACV,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,iCAAiC,CAAC;AAEzC,eAAO,MAAM,4BAA4B,EACvC,8BAAuC,CAAC;AAE1C,eAAO,MAAM,mCAAmC;;;;;;;;;;;;CAYF,CAAC;AAgB/C,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,GACf,mBAAmB,EAAE,CAsBvB;AA0DD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,QAAQ,EAAE,IAAI,GAAG,IAAI,GAAG,GAAG,EAC3B,QAAQ,EAAE,MAAM,GACf,qBAAqB,CAKvB;AA0dD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,mBAAmB,EAAE,EACtC,GAAG,GAAE,IAAiB,EACtB,MAAM,GAAE,yBAA+D,GACtE,yBAAyB,CA6D3B;AA+DD,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,yBAAyB,GAChC,SAAS,iBAAiB,EAAE,CA+E9B"}
+{"version":3,"file":"telemetry-acceptance.d.ts","sourceRoot":"","sources":["../../src/public/telemetry-acceptance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAEV,yBAAyB,EACzB,yBAAyB,EAGzB,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,iCAAiC,CAAC;AAEzC,YAAY,EACV,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,iCAAiC,CAAC;AAEzC,eAAO,MAAM,4BAA4B,EACvC,8BAAuC,CAAC;AAE1C,eAAO,MAAM,mCAAmC;;;;;;;;;;;;CAYF,CAAC;AAgB/C;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,GACf,mBAAmB,EAAE,CAuBvB;AA0DD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,QAAQ,EAAE,IAAI,GAAG,IAAI,GAAG,GAAG,EAC3B,QAAQ,EAAE,MAAM,GACf,qBAAqB,CAKvB;AA0dD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,mBAAmB,EAAE,EACtC,GAAG,GAAE,IAAiB,EACtB,MAAM,GAAE,yBAA+D,GACtE,yBAAyB,CA6D3B;AA+DD,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,yBAAyB,GAChC,SAAS,iBAAiB,EAAE,CA+E9B"}

package/dist/public/telemetry-acceptance.js

@@ -15,6 +15,14 @@ export const DEFAULT_TELEMETRY_ACCEPTANCE_POLICY = {
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+/**
+ * Parse Kibi operation events from `.kb/usage.log`.
+ *
+ * Host plugin hooks share the log and tag their rows `interface: "hook"`.
+ * Those rows describe agent activity around Kibi calls, not Kibi operations,
+ * so they are dropped here: otherwise a busy editing session would push every
+ * operation out of the bounded acceptance window.
+ */
 export function parseTelemetryUsageLog(contents) {
     const events = [];
     for (const [index, line] of contents.split(/\r?\n/).entries()) {
@@ -32,6 +40,8 @@ export function parseTelemetryUsageLog(contents) {
         if (!isRecord(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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {

package/src/public/diagnostic-usage.ts

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
-import { appendFileSync, mkdirSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 import {
   appendPayloadCountField,
@@ -241,6 +242,60 @@ export function deriveDiagnosticUsageFields(
   return fields;
 }
 
+/**
+ * Whether the operator opted into usage telemetry through the environment.
+ *
+ * `KIBI_DIAGNOSTIC_MODE` is the one opt-in shared with the MCP server, so a
+ * single setting covers both peer surfaces. `KIBI_CLI_DIAGNOSTIC_MODE` is the
+ * older CLI-only spelling and keeps working.
+ */
+export function diagnosticEnvOptIn(
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  return ["KIBI_DIAGNOSTIC_MODE", "KIBI_CLI_DIAGNOSTIC_MODE"].some((key) => {
+    const value = env[key]?.trim().toLowerCase();
+    return value === "1" || value === "true";
+  });
+}
+
+/**
+ * The host that ran this CLI call. Hosts that launch Kibi set `KIBI_HOST`;
+ * Claude Code marks every shell it runs with `CLAUDECODE=1`, which is the
+ * only ambient signal trusted here. Anything else stays `unknown`.
+ */
+export function diagnosticCliHost(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const explicit = env.KIBI_HOST?.trim() || env.KIBI_MCP_HOST?.trim();
+  if (explicit) return explicit;
+  return env.CLAUDECODE === "1" ? "claude-code" : "unknown";
+}
+
+let cachedCliPackageVersion: string | null | undefined;
+
+function cliPackageVersion(): string | null {
+  if (cachedCliPackageVersion !== undefined) return cachedCliPackageVersion;
+  cachedCliPackageVersion = null;
+  let current = path.dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    const candidate = path.join(current, "package.json");
+    if (existsSync(candidate)) {
+      try {
+        const parsed: unknown = JSON.parse(readFileSync(candidate, "utf8"));
+        if (isRecord(parsed) && typeof parsed.version === "string") {
+          cachedCliPackageVersion = parsed.version;
+        }
+      } catch {
+        // An unreadable manifest leaves the version unknown.
+      }
+      return cachedCliPackageVersion;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
 export function appendCliDiagnosticUsage(input: DiagnosticUsageInput): void {
   const finishedAt = input.finishedAt ?? new Date();
   const requestId = input.requestId ?? `cli-${randomUUID()}`;
@@ -256,6 +311,9 @@ export function appendCliDiagnosticUsage(input: DiagnosticUsageInput): void {
       request_id: requestId,
       tool: input.tool,
       interface: "cli_json",
+      host: diagnosticCliHost(),
+      package_version: cliPackageVersion(),
+      workspace_root: input.workspaceRoot,
       telemetry: input.telemetry,
       business_args: input.businessArgs,
       status: input.status,

package/src/public/operations/specs/bootstrap.ts

@@ -1,7 +1,9 @@
 import { executePlanBootstrap } from "../../../operations/bootstrap/generate.js";
-import type {
-  PlanBootstrapArgs,
-  PlanBootstrapResult,
+import {
+  KNOWLEDGE_SOURCE_AUTHORITIES,
+  KNOWLEDGE_SOURCE_KINDS,
+  type PlanBootstrapArgs,
+  type PlanBootstrapResult,
 } from "../../../operations/bootstrap/types.js";
 import type { OperationSpec } from "../types.js";
 
@@ -17,7 +19,7 @@ export const 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.",
+    "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: {
@@ -86,6 +88,78 @@ export const planBootstrapSpec = {
             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/src/public/operations/symbol-repair-plan.ts

@@ -71,7 +71,9 @@ export async function inspectCoordinateRepairs(
         : {}),
     };
   });
-  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;

package/src/public/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/src/public/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/src/public/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/src/public/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/src/public/telemetry-acceptance.ts

@@ -50,6 +50,14 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
+/**
+ * Parse Kibi operation events from `.kb/usage.log`.
+ *
+ * Host plugin hooks share the log and tag their rows `interface: "hook"`.
+ * Those rows describe agent activity around Kibi calls, not Kibi operations,
+ * so they are dropped here: otherwise a busy editing session would push every
+ * operation out of the bounded acceptance window.
+ */
 export function parseTelemetryUsageLog(
   contents: string,
 ): TelemetryUsageEvent[] {
@@ -71,6 +79,7 @@ export function parseTelemetryUsageLog(
         `Failed to parse .kb/usage.log line ${index + 1}: expected object`,
       );
     }
+    if (parsed.interface === "hook") continue;
     events.push(parsed as TelemetryUsageEvent);
   }
   return events;