kibi-runtime 2.0.2 → 2.2.0

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

@@ -23,6 +23,7 @@ per operation. Effects are authoritative for mutability and adapter annotations.
 | `kb_upsert` | `upsert` | --input JSON | write | yes | kb-write, workspace-write | peer; capability-selected | kibi.kb_upsert.v1 | yes | unsafe | no | yes |
 | `kb_delete` | `delete` | --input JSON | write | yes | kb-write, workspace-write | peer; capability-selected | kibi.kb_delete.v1 | yes | unsafe | no | yes |
 | `kb_check` | `check` | --input JSON or flags | read | yes | kb-read, workspace-read | peer; capability-selected | kibi.kb_check.v1 | no | safe | no | yes |
+| `kb_prepare_impact_review` | `prepare-impact-review` | --input JSON | read | no | workspace-read, kb-read | peer; capability-selected | kibi.kb_prepare_impact_review.v1 | no | safe | no | yes |
 | `kb_sparql_remote` | `sparql-remote` | --input JSON | read | no | network-read | peer; capability-selected | kibi.kb_sparql_remote.v1 | no | safe | yes | yes |
 | `kb_compile_intent` | `compile-intent` | --input JSON | read | yes | kb-read, workspace-read | peer; capability-selected | kibi.kb_compile_intent.v1 | no | safe | no | yes |
 | `kb_apply_plan` | `apply-plan` | --input JSON | write | yes | kb-read, kb-write, workspace-read, workspace-write | peer; capability-selected | kibi.kb_apply_plan.v1 | yes | unsafe | no | yes |
@@ -40,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.0.2",
+  "version": "2.2.0",
   "description": "Narrow first-party runtime contracts and adapters for Kibi operations.",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,13 +13,14 @@
   },
   "files": ["dist"],
   "scripts": {
-    "build": "tsc -p tsconfig.json && bun build src/index.ts --outfile dist/index.js --target node --format esm --packages bundle --external kibi-core --external kibi-plugin-builtin && bun build ../cli/src/engine-daemon.ts --outfile dist/engine-daemon.js --target node --format esm --packages bundle --external kibi-core && rm -rf dist/skills && mkdir -p dist/skills && cp -r src/skills/. dist/skills/",
+    "build": "tsc -p tsconfig.json && bun build src/index.ts --outfile dist/index.js --target node --format esm --packages bundle --external kibi-core --external kibi-plugin-builtin --external kibi-swipl --external 'kibi-swipl-*' && bun build ../cli/src/engine-daemon.ts --outfile dist/engine-daemon.js --target node --format esm --packages bundle --external kibi-core --external kibi-swipl --external 'kibi-swipl-*' && rm -rf dist/skills && mkdir -p dist/skills && cp -r src/skills/. dist/skills/",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
     "gray-matter": "^4.0.3",
-    "kibi-core": "^0.14.0",
-    "kibi-plugin-builtin": "^0.3.0"
+    "kibi-core": "^0.14.1",
+    "kibi-plugin-builtin": "^0.4.0",
+    "kibi-swipl": "^1.0.0"
   },
   "devDependencies": {
     "kibi-cli": "workspace:*"