npm - kibi-cursor - Versions diffs - 2.1.0 → 2.2.0 - Mend

kibi-cursor 2.1.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/.cursor-plugin/plugin.json +2 -2
package/CHANGELOG.md +43 -49
package/README.md +6 -4
package/agent-plugin/plugin.json +1 -1
package/agent-plugin/skills/kibi-bootstrap/SKILL.md +47 -11
package/agent-plugin/skills/kibi-bootstrap/resources/bootstrap.md +6 -1
package/agent-plugin/skills/kibi-usage/SKILL.md +14 -0
package/agent-plugin/skills/kibi-usage/resources/operation-access.md +5 -0
package/commands/kibi-bootstrap.md +4 -1
package/dist/.cursor-plugin/plugin.json +2 -2
package/dist/commands/kibi-bootstrap.md +4 -1
package/dist/hook-runner.d.ts +10 -0
package/dist/hook-runner.js +29 -0
package/dist/skills/.canon-hash.json +4 -4
package/dist/skills/kibi-bootstrap/SKILL.md +47 -11
package/dist/skills/kibi-bootstrap/resources/bootstrap.md +6 -1
package/dist/skills/kibi-usage/SKILL.md +14 -0
package/dist/skills/kibi-usage/resources/operation-access.md +5 -0
package/package.json +2 -2
package/skills/.canon-hash.json +4 -4
package/skills/kibi-bootstrap/SKILL.md +47 -11
package/skills/kibi-bootstrap/resources/bootstrap.md +6 -1
package/skills/kibi-usage/SKILL.md +14 -0
package/skills/kibi-usage/resources/operation-access.md +5 -0

package/.cursor-plugin/plugin.json CHANGED Viewed

@@ -1,8 +1,8 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "2.1.0",
-  "description": "Optional Cursor adapter for Kibi. Requires SWI-Prolog 9+ and project-local kibi-cli, kibi-mcp, and kibi-core before the bundled MCP server can start.",
+  "version": "2.2.0",
+  "description": "Optional Cursor adapter for Kibi. Requires project-local kibi-cli, kibi-mcp, and kibi-core (SWI-Prolog is bundled on Linux and macOS) before the bundled MCP server can start.",
   "license": "AGPL-3.0-or-later",
   "author": {
     "name": "Kibi"

package/CHANGELOG.md CHANGED Viewed

@@ -1,11 +1,53 @@
 # kibi-cursor
+## 2.2.0
+### Minor Changes
+- f93dcdd: Bootstrap no longer learns only from the code. The agent now starts with a short interview: it asks where product intent already lives (issue trackers such as Jira or YouTrack, wikis, specs, decision logs), which sources are authoritative or stale, and reads them through its own connectors. The bootstrap plan records those sources and the intent claims harvested from them, so each requirement taken from a ticket or page cites it and the citation is part of the approved plan hash. Kibi still never contacts those sources itself.
+  - feat(cli): `kb_plan_bootstrap` / `plan-bootstrap` accept `bootstrapContext.knowledgeSources` (id, kind, title, locator, authority, optional connector) and `bootstrapContext.intentClaims` (statement, sourceId, reference, optional excerpt). Both are normalized into `declaredContext` and bound into `planHash`. Grounded claims from authoritative or supporting sources become `req` candidates with `sourceKind: intent_claim`, citation evidence, and `text_ref: <sourceId>:<reference>`. Ungroundable claims become authoring follow-ups, stale sources are suppressed with `stale_knowledge_source`, and claims citing undeclared sources are reported as non-blocking diagnostics. A `needs_context` plan without declared sources asks for them.
+  - feat(skills): `kibi-bootstrap` 3.1.0 leads with the source interview before planning; the MCP `/kibi-bootstrap` prompt and the Cursor and ZCode commands follow it.
+  - docs: README, landing page, quick start, and install guide lead with a copy-paste agent setup prompt; manual installation moves behind a toggle.
+### Patch Changes
+- 676bac9: The Claude Code, Codex, Cursor, and ZCode plugins now tell the Kibi MCP server which workspace each call is about, so sessions working in a git worktree are answered from that worktree's branch instead of the checkout the server started in. Nothing changes for sessions that stay in one project.
+  - Each plugin's pre-tool hook adds `workspaceRoot`, the agent's current Kibi workspace, to every Kibi MCP call. Claude Code, Cursor, and ZCode send it without a permission decision so the host's own approval flow is unchanged; Codex requires `permissionDecision: "allow"` for input rewrites, which does not override a server's tool approval mode.
+  - `kibi-agent-core` exports `KIBI_WORKSPACE_ARGUMENT`, `isKibiMcpToolName`, and `stampKibiWorkspace` for the plugins.
+  - The Codex hook parser now reads `hook_event_name`, the field Codex actually sends; the Claude and ZCode `PreToolUse` matchers include `mcp__.*__kb_.*`.
+  - The ZCode launcher sets `KIBI_MCP_HOST=zcode` so its usage rows are attributed like the other hosts'.
+- Updated dependencies [676bac9]
+  - kibi-agent-core@0.1.1
+## 2.1.1
+### Patch Changes
+- 7aa1471: Kibi can now run without a hand-installed SWI-Prolog. It looks for an explicit `KIBI_SWIPL` executable first, then the tested SWI-Prolog build shipped in the new `kibi-swipl` platform packages, and only then `swipl` on `PATH` (9.0 or newer). `KIBI_SWIPL=system` skips the bundle. `kibi doctor` now reports which runtime was chosen (source, path, version), checks that every required library loads, and explains which platform package to add when the bundle is missing. A running Kibi engine that was started with a different SWI-Prolog is restarted instead of reused. Release builds now ship the tested SWI-Prolog for Linux x64, Linux arm64, macOS arm64, and macOS x64 inside the `kibi-swipl-<platform>` packages, and an install that skips optional dependencies still succeeds and explains which package to add.
+  - kibi-cli: add `resolveSwipl()` (env, bundled with manifest and SHA-256 verification, PATH), a per-process cache, and `SWI_HOME_DIR` for bundled builds in both `PrologProcess` spawn paths.
+  - kibi-cli: engine handshake and requests carry the resolved `<bin>@<version>`; the daemon rejects mismatches and clients replace a mismatched daemon.
+  - kibi-cli: `doctor` SWI-Prolog check uses the resolver and loads all required libraries.
+  - kibi-runtime: depend on `kibi-swipl`; keep it and the platform packages external in both bundles.
+  - kibi-cursor: the worktree resolver accepts `KIBI_SWIPL` or a bundled `kibi-swipl-*` binary in the candidate's installed packages.
+  - Release: the publish workflow builds the SWI-Prolog archives in its own run, verifies each SHA-256 sidecar, pinned provenance, and binary checksum, materializes symlinks (npm drops them), packs the four platform packages, and installs the packed tarballs with npm on runners with no SWI-Prolog before publishing; a separate dry-run workflow packs without any publish path.
+  - New packages `kibi-swipl` and `kibi-swipl-<platform>` start at 1.0.0 outside this changeset and version together through a changesets fixed group.
+- db5376c: Projects can now opt into impact reviews that bind a change to its exact source, knowledge decisions and trusted analysis policy. Kibi validates both staged changes and a complete pull-request diff, rejects stale review evidence, and lets agents prepare an unauthored review template through the CLI or MCP instead of hand-assembling one. Every decision and reviewer field stays for an agent to write; preparation never approves or proves anything.
+  - Add versioned impact policy and review schemas, immutable review fingerprints, reviewed Python decorator coordinate migration and the trusted aggregate `check-diff` command.
+  - Add the read-only `prepare-impact-review --input` CLI route and `kb_prepare_impact_review` MCP operation; regenerate the bundled operation-access catalog for the agent integrations.
+  - Keep the sample CI workflow inactive until it is adopted on a protected target.
+- 3d78159: Setting up Kibi no longer starts with installing SWI-Prolog. The documentation now says that Linux (x64 and arm64, glibc 2.28 or newer) and macOS (Apple silicon and Intel) need nothing beyond Node.js 22, explains the lookup order and the `KIBI_SWIPL` and `KIBI_SWIPL=system` overrides, and shows how `kibi doctor` reports which SWI-Prolog is in use and what to do when an install skipped the bundled runtime (`--omit=optional`, pnpm `supportedArchitectures`). Manual instructions stay for Alpine and native Windows. The GitHub Pages report workflows that `kibi init` can write no longer install SWI-Prolog by hand, because `npm ci` brings the bundled runtime with it.
+  - kibi-cli: drop the `apt-get install swi-prolog` step from the shipped `kibi-report.yml` and `kibi-badge.yml` workflow templates.
+  - kibi-cursor, kibi-claude: README and plugin manifest prerequisites say SWI-Prolog is bundled on supported platforms and only needed on `PATH` elsewhere.
+  - Kibi's own CI and proof now run the pipeline-built bundled SWI-Prolog (one job keeps a system install with `KIBI_SWIPL=system`), and the release dry run follows the README quick start with the packed tarballs on four platforms; neither ships in a package.
 ## 2.1.0
 ### Minor Changes
 - f01838e: The Cursor plugin now asks the agent to consult Kibi before it edits a file, not only after. Every nudge used to fire once the change was already written — the post-edit message opened with "After editing" twice — so the plugin could only ever prompt repair, never inform the change. Before an edit, the plugin now names only requirements the file explicitly implements and asks for them to be read first, which is the one point where retrieval can still change what gets written.
   - Emit source-linked pre-edit guidance from `preToolUse` for edit-like tools, resolved synchronously from the symbol manifest so no KB round-trip is added to the edit path.
   - Name up to three `implements` requirement targets for the file, or ask for discovery and ownership when no requirement ownership is known.
   - Narrow the post-edit message to the impact review that only becomes possible once the change exists, and stop repeating the retrieval ask there.
@@ -17,26 +59,22 @@
   reports them with a prefix, such as `mcp__kibi__kb_check`. Before this fix,
   an agent that correctly ran an impact check through a prefixed tool name
   still got a stop reminder to run it, because the plugin never saw the check.
   - `kb-mcp-tools.ts` in each adapter gains `canonicalKbToolName`, which strips
     `mcp__<server>__`, `MCP:`, and `kibi_` prefixes before matching `kb_*`
     operations.
   - The Codex hook bundle is regenerated.
 - 25f11b1: The badge that `kibi init --github` adds to your README now links to the published explanation of the `% proven` metric at https://looted.github.io/kibi/ instead of the GitHub rendering of the Markdown source. The Kibi documentation site moved to the root of that domain, with the requirement-health report still under `/kibi-report/`. The Cursor and OpenCode package READMEs also link to the published guides, so the links work when you read them on npm.
   - cli: `KIBI_METRIC_DOCS_URL` points at `https://looted.github.io/kibi/guide/github-integration.html#what-the-badge-means`.
   - cursor, opencode: README setup and troubleshooting links point at the published guide pages instead of repository-relative or GitHub blob URLs.
   - repo tooling (not published): the docs site builds into the GitHub Pages root and renders `llms.txt` as one H2 link list per catalog group from the shared page metadata.
 - 5a06c03: Kibi's agent plugins now share one fast, consistent implementation for source-path classification, Kibi MCP tool recognition, and symbol-manifest indexing. Codex and ZCode now recognize production code outside `src/`, while Cursor reuses the same size-and-mtime-keyed scanner as Claude instead of parsing the full symbol manifest before an edit.
   - Add `kibi-agent-core` as the common Node 18-compatible hook-helper package.
   - Keep host adapters thin while preserving their host-specific event and state contracts.
   - Replace Cursor's YAML parser dependency with the shared cached line scanner.
 - f01838e: Usage telemetry stays off by default for every client, and there is now a supported way to turn it on. Previously the only way to capture usage was to hand-write an MCP command line with `--diagnostic-mode`, which meant anyone using a shipped plugin recorded nothing at all and had no documented alternative. Operators can now opt in with an environment variable, and once they do, each row identifies the host, package version, and checkout that produced it, so behavior can be compared across editors, worktrees, and Kibi versions.
   - Honor `KIBI_DIAGNOSTIC_MODE=1` alongside the existing `--diagnostic-mode` flag, for hosts where a plugin owns the MCP command line.
   - Stamp `interface`, `host`, `package_version`, and `workspace_root` on every usage row.
   - Set `KIBI_MCP_HOST` from the Cursor and Codex launchers for attribution only; it never enables logging, and installing or enabling a plugin never starts telemetry.
@@ -48,7 +86,6 @@
   When you model a new requirement, Kibi now ranks the subjects that already exist and either reuses one or explicitly declares a new one. It also flags claims that look like possible duplicates. An intentional restatement can be recorded with the new `restates` relationship. Skills and docs now recommend naming entities by the behavior they govern (`REQ-cli-gc`) instead of a sequence number (`REQ-042`). Existing numbered IDs stay valid.
   Predicate schemas can now declare the allowed values for an argument, plus the old spellings that map onto them. New facts must use those values. `kibi check` reports predicate facts that don't match any schema, and `kibi migrate` can fix the mechanical cases after you approve the plan hash. It moves a fact to the only namespace whose schema matches, and rewrites old spellings to the declared value. Everything that needs judgment stays a review item.
   - core: new `semantic_quality.pl` (`entity-id-style`, `domain-redundancy`, `domain-implication`, `subject-key-identity`, `subject-key-shape`, `ontology-quality`) and `units.pl`. Unit canonicalization is used for comparison only, and unknown or ambiguous units such as `KB` are never equated. Adds the `restates` req→req relationship and an optional `diagnosticSeverity` in the rule registry. Adds `:- encoding(utf8)` to modules that contain non-ASCII text.
   - cli/mcp: `restates` is wired through the extractors, schemas, and mutation paths. `entity-id-style` warnings are reported on `kb_upsert` creates and on staged added or renamed entity files. `kb_model_requirement` returns `vocabularyAlignment` (subject decision, candidates, redundancy candidates, stamps, `fallbackUsed`). Ontology-quality thresholds can be set with `KIBI_ONTOLOGY_QUALITY_MAX_SINGLETON_RATIO` / `KIBI_ONTOLOGY_QUALITY_MIN_FACTS`. `kb_compile_intent` create mode now keeps a caller-supplied `requirementId`. `kibi check --staged` now also prints its pass line when metadata-only staged changes have only advisory findings, matching the staged-symbol path.
   - cli/mcp: `predicate_schema` facts accept `argument_constants` and `argument_aliases`, stored like `rule_ir` as JSON. `kb_upsert` / `kb_validate_upsert` reject malformed vocabularies and predicate facts that use undeclared values or aliases. `kb_suggest_predicates` binds aliases to their constant and leaves undeclared values unbound. The new advisory TypeScript rule `predicate-schema-conformance` checks predicate facts against project schemas and the built-in catalog. Its mechanical repairs become automatic `predicate_schema_alignment` migration actions that carry the exact `kb_upsert` input and re-read the fact before writing.
@@ -66,19 +103,16 @@
 ### Patch Changes
 - 96a1ebd: Local Cursor MCP builds now compile plugin SDK/builtin dist before the CLI, so a fresh checkout no longer fails with a missing `kibi-plugin-builtin` type package.
   - `build:cli-stack` runs plugin-sdk + plugin-builtin + CLI
   - Worktree resolver uses that stack instead of `build:cli` alone
 - 188f875: No user-facing behavior change: `kibi-runtime` now resolves its bundled-skills directory lazily on first use instead of at import time, `isWithinRoot` drops a redundant same-path comparison, `kibi-cursor` drops a provably dead `planDelivered` early return and an always-true stdin branch, and the hook runners' stdin buffering is simplified to an unconditional `Buffer.from`. The reshaping lets the new mutation-testing suite (`docs/mutation-testing.md`, run via `bun run test:mutation`) prove these paths exhaustively — the suite holds a 100% mutation score over `kibi-runtime`, `kibi-codex`, and `kibi-cursor` sources.
 - db07d8f: Proof diagnostics now agree with the Prolog decision: a structural type-shape unit contract is shown as qualifying, `kibi proof impact` compares against the Git HEAD baseline and exits 0 after a successful report, and mixed-role symbols fail the strict proof integrity gate.
   - Mode-aware candidate evaluation in Prolog; receipt fallback uses `test_receipt_evidence(Context, TestId, Evidence)`.
   - `proof impact` reads `HEAD:proof/baseline.json` with no worktree fallback; diagnostic exit 0.
   - Strict proof workflow and baseline checker include canonical `symbol-traceability`.
 - f33a665: Proof failures now name the exact requirement, symbol, and why each `covered_by` candidate did not qualify, without changing what counts as proven. Agents can inspect a requirement with `kibi proof explain` and compare current proof state to the committed `proof/baseline.json` snapshot with `kibi proof impact`, instead of reverse-engineering Prolog or guessing from aggregate counts.
   - Keep `kibi.requirement-proof.v3` and add additive production-symbol `explanations` plus TEST `testResolutions` on the same Proof.
   - Ratchet `proof/baseline.json` to v2 with compact requirement fingerprints; aggregate counts stay the ratchet.
   - Add `kibi proof explain` and `kibi proof impact` as Proof projections, mixed-role leftovers in `symbol-traceability`, and advisory `proof-contract-symbols`.
@@ -89,7 +123,6 @@
 ### Major Changes
 - 812c201: Kibi's proof layer is now runner-neutral: any test runner, script, or harness can prove requirements, and Playwright is no longer built into the proof model.
   - `kibi prove` replaces `kibi verify` as the single command to run configured proof producers and record evidence. Proof contracts (`kibi.proof-contract.v1`) declare explicit obligations (`symbol_id` + `target`) executed by a configured integration in `.kb/proof/integrations.json`; `kibi proof inspect` discovers test infrastructure deterministically; one producer run can satisfy many test contracts, and re-ingestion is idempotent.
   - Evidence moves to the `kibi.proof-run.v1` artifact (typed environment, run-level outcome, factual attempt history with `native_case`/`aggregate_run` provenance) evaluated into `kibi.proof-receipt.v1` receipts bound to the live snapshot, contract hash, and effective execution fingerprint. Command proof is the universal fallback, so every project can prove requirements without a first-party framework adapter; strict first-attempt policy never upgrades unknown attempt history into passing evidence.
   - Breaking removals: `kibi verify`, `kb_ingest_verification`, `kibi.playwright-run.v1`, `verification_contract`/`verification_receipts` entity fields (replaced by `proof_contract`/`proof_bindings`/`proof_receipts`), the `required_case_symbols`×`required_projects` Cartesian contract, and `retries` fields. Migrate by re-running `kibi prove` after bootstrap configures proof for your repository.
@@ -99,12 +132,10 @@
 ### Patch Changes
 - b0271ac: Cursor now starts the bundled Kibi MCP server reliably when it launches plugin processes from a home directory or another unrelated working directory. Consumer workspaces with spaces continue to resolve their project-local `kibi-mcp` installation, while the portable Agent Plugin keeps its separate `npx --no-install` configuration.
   - Fix `kibi-cursor` MCP launcher arguments to use Cursor's `${CURSOR_PLUGIN_ROOT}` expansion.
   - Add source-install manifest regression coverage for consumer-local resolution from unrelated host directories.
 - b1682f1: Agents receive clearer guidance for repairing the actual supplied mutation request and preserving approved predicate bindings. The scoped additions retain the existing workflow while separating payload recovery from conditional relational modeling.
   - Update `kibi-usage` to 2.1.2 in CLI/runtime sources and the generated Codex/Cursor distributions.
   - Preserve the other three skills and all existing resource content.
   - Retain production-adoption safeguards; development comparisons are not held-out evidence.
@@ -113,12 +144,10 @@
   same entry paths tests already spawn as processes. In-process coverage can
   exercise stdin, CLI guards, and realpath failures instead of leaving those
   lines invisible to Codecov.
   - Export hook CLI helpers and Agent Plugin / launcher internals for tests.
   - Use a namespace `fs` import in skill validation so realpath errors are testable.
 - 5999143: Agent-facing skill docs now use the current status field names, so agents following the freshness and E2E receipt workflows look for fields that actually exist in `kb_status` output instead of stale ones.
   - Bundled `kibi-freshness` and `kibi-usage` skills (all agent mirrors) now reference `proofSnapshotChanges` and `proofSnapshot` (previously `verificationSnapshotChanges`/`verificationSnapshot` from the pre-proof-architecture status schema).
   - The skillopt-eval harness reads `proofSnapshot*` status fields and its held-out eval prompts name the current fields, so "dirty editor path" evidence gathering works against live status output again.
@@ -129,7 +158,6 @@
 ### Patch Changes
 - Cursor agents now get an always-on CLI recipe when Kibi MCP tools are missing, instead of treating Kibi as unavailable.
   - Put the exact `npx --no-install kibi <route> --input -` command, MCP-to-CLI name mapping, and Shell-approval language in the always-applied workflow rule.
   - Keep published plugin hooks advisory and untrusted by default; dogfood still opts into `--trusted-workspace` locally.
   - Document the operator prerequisites (Agent mode, Shell, trusted workspace, project-local CLI) for the fallback to run.
@@ -141,7 +169,6 @@
 - 9e6fb3f: Kibi now uses one opinionated project contract: all Kibi-managed knowledge lives under `.kb/`, check enforcement is owned by the installed Kibi version, and projects can no longer weaken health by disabling rules or relocating entity paths in `.kb/config.json`. Existing repositories must run `kibi migrate --yes` to move legacy `documentation/...` knowledge into the canonical layout and adopt `.kb/manifest.json`.
   Advisory modeling checks still run by default, but they report as non-blocking quality diagnostics instead of failing `kibi check`. Migration rewrites the old blanket `.kb/` gitignore stanza so authored lanes are trackable, and a malformed leftover `config.json` blocks the one-way cutover instead of guessing default paths.
   - Remove user-configurable entity paths and persistent `checks.rules` overrides; retire `.kb/config.json` after migration.
   - Introduce `.kb/manifest.json` for Kibi-owned lifecycle metadata (schema version, semantic backfill state).
   - Add one-way legacy storage migration (`documentation/` and custom configured paths → `.kb/<lane>/`).
@@ -155,7 +182,6 @@
   - Pending relationship shards are not treated as symbols manifests during source discovery.
 - 4c75e4d: Kibi onboarding now separates repository initialization from teaching Kibi about an existing codebase. After `kibi init`, an agent can run the `kibi-bootstrap` workflow to produce a reviewable, hash-bound plan and apply the exact approved plan safely. The old autopilot and init-kibi public names are removed so new users see one clear bootstrap path.
   - Replace `kb_autopilot_generate`/`autopilot-generate` with `kb_plan_bootstrap`/`plan-bootstrap`.
   - Add `kibi.bootstrap-plan.v1` validation, deterministic approval hashes, dependency ordering, stale-plan checks, and typed bootstrap recovery through `kb_apply_plan`.
   - Synchronize the four canonical skill mirrors and update client adapters, docs, fixtures, and SkillOpt cases.
@@ -167,7 +193,6 @@
   effect and repair information, while branch stores are hashed and explicitly
   identity-bound. The mutation path can author tracked source documents and
   canonical relationship shards without staging or committing them.
   - Add the `kibi-runtime` first-party integration package.
   - Add exact branch-store manifests, explicit legacy migration/quarantine, and
     typed result/effect contracts.
@@ -175,24 +200,20 @@
     approval plans.
 - 3d7d04f: Generic MCP and CLI agents now discover Kibi's operating rules from bundled skills instead of a long copy-paste prompt. Improving an existing product KB is covered by a `kibi-usage` resource rather than a second manual, so agent guidance stays in one place and cannot drift from the packaged workflow.
   - Add `kibi-usage` `resources/kb-improvement.md` and bump that skill to 2.1.0.
   - Replace `docs/prompts/llm-rules.md` with `docs/generic-agent-onboarding.md`.
   - Remove the obsolete retroactive-init prompt; bootstrap stays in the `kibi-bootstrap` skill.
 - 29793c7: The Cursor stop hook no longer starts an extra Kibi follow-up after you only deliver a plan. Reads and search no longer look like source edits, so plan mode can finish without an impact-check nudge. If that same turn actually edited source or updated the knowledge base, the existing follow-up still runs.
   - Record dirty paths only from known editable tools.
   - Treat `CreatePlan` as plan delivery and stay silent at stop unless that turn also edited source or mutated the KB.
   - Skip follow-up when `stop.status` is `aborted` or `error`.
 - 8db2e37: Cursor plugin users can now enable Kibi without adding a separate project MCP configuration. The plugin finds the `kibi-mcp` version installed in the opened project, starts it inside that workspace, and reports a clear setup error when the dependency is missing. It never downloads or falls back to a global Kibi runtime.
   - Replace the plugin MCP `npx --no-install` command with the packaged consumer-workspace launcher.
   - Cover isolated and packed plugin launches, workspace selection, package-layout resolution, exit codes, and signal forwarding.
 - 535dea8: Agents can now keep working in synthetic, detached, or unreadable workspaces while Kibi reports the migration work it can evaluate. Coverage and checks preserve their useful domain results when branch status is unavailable, and the Codex/Cursor skill assets now stay aligned with their published plugin metadata.
   - Keep status-derived migration actions read-only and append them only when branch resolution succeeds.
   - Preserve the shared migration-plan contract across coverage and checks without requiring a Prolog-backed status query in non-Git harnesses.
   - Synchronize plugin manifests and freshness skill CLI examples for the next coordinated patch release.
@@ -202,7 +223,6 @@
   edges can no longer hide a newer contradictory policy merely by making that
   newer requirement non-current. Relationship checks also block authored links
   that have silently disappeared from compiled knowledge.
   - Document `supersedes` as new-to-old across bundled and generated skills.
   - Reject reversed supersession when tracked source history proves that the
     purported replacement predates its target.
@@ -253,7 +273,6 @@
 ### Patch Changes
 - The published Cursor plugin now launches the `kibi-mcp` installed in the opened project, even when Cursor starts plugin processes from the plugin installation directory. The launcher preserves the consumer workspace as the child cwd and `KIBI_WORKSPACE`, and fails with an actionable message when the project-local package is missing.
   - Replace plugin MCP's ambient `npx --no-install` invocation with the packaged consumer-local resolver.
   - Add isolated and packed-artifact coverage for workspace resolution, package layouts, exit codes, signals, and missing-runtime failures.
@@ -262,7 +281,6 @@
 ### Patch Changes
 - Existing Kibi installations now receive an agent-guided migration workflow instead of opaque repair advice. Status, checks, and coverage expose one deterministic, hash-bound action plan; agents can safely apply only explicitly approved automatic repairs while semantic, proof, package, and operator work remains visible for review. This makes damaged or legacy KBs recoverable without direct `.kb` edits and gives every run an auditable post-application readback.
   - Add `kibi.migration-plan.v2` fragments to the 21-operation surfaces and support hash/action authorization in `kb_apply_plan` and `kibi migrate --apply-safe`.
   - Add lazy status/planning and deterministic schema, branch, storage, coordinate, and recovery action execution with workspace-root-safe CLI/MCP parity.
   - Refresh agent skills, traceability fixtures, and SkillOpt coverage for migration safety boundaries and five-axis closeout reporting.
@@ -272,13 +290,11 @@
 ### Patch Changes
 - de7b85a: Verification contracts can now evolve without forcing projects to erase valid historical test evidence. Kibi preserves every earlier receipt, accepts a newly appended receipt for the current contract, and only treats evidence matching both the current contract and live code snapshot as proof.
   - Separate immutable receipt-history validation from current-contract binding during verification ingest.
   - Report `verification_contract_mismatch` as an explicit proof gap until current-contract evidence is appended.
   - Teach the usage skill and SkillOpt evaluator to preserve older-contract receipts and forbid history rewrites.
 - 584336b: Agents now get consistent guidance when execution proof, structural coverage, and KB freshness disagree. Current-contract E2E evidence is recorded as v2 without rewriting history, and full checks no longer report a contradictory weak-depth warning when the same live receipt already proves the scenario-backed test. Receipt freshness repairs also identify the affected requirements and tests so agents can rerun the exact contract.
   - Share snapshot-bound proof evidence with full quality diagnostics.
   - Add bounded receipt-gap telemetry and v2-native remediation guidance.
   - Document and test the new receipt and proof-aware diagnostic requirements.
@@ -286,13 +302,11 @@
   - Keep the MCP package contract verifier self-contained with an explicit semver development dependency and matching workspace lock ranges.
 - Kibi can now explain a missing or damaged branch-local KB without changing it. Agents receive a precise recovery path, preserving the existing store before a deliberate rebuild, and no longer need to guess whether a clean check also means a clean, fresh KB.
   - Add non-mutating branch-store inspection to status and a preview-first `kibi branch recover --apply` workflow.
   - Restrict branch migration to the detected historical `master` -> legacy `main` compatibility attachment; arbitrary branch moves are refused.
   - Refresh CLI/MCP status documentation, mirrored agent skills, and release-gate packed consumer coverage.
 - ef75929: Kibi’s release checks now validate compiled package APIs and dependency ranges in isolated npm and pnpm consumers, while the usage skill and private SkillOpt evaluator report task completion, KB freshness, verification, proof, and accepted limitations independently. Consumer repositories keep ownership of their local artifact update scripts and dependency overrides.
   - Remove library-side consumer dogfood installers and retain release-only packed checks.
   - Add deterministic closeout expectations and dogfood-derived held-out cases.
@@ -301,7 +315,6 @@
 ### Patch Changes
 - Dogfood projects now get branch-local knowledge bases that follow the exact Git ref, actionable stale-source diagnostics, and a sanctioned relationship cleanup path. Verification receipts and packed package provenance are stricter and reproducible, while agents receive conservative symbol-recovery guidance and explicit interim-state signals. This prevents silent `master`/`main` drift and makes passing E2E evidence distinguishable from complete semantic proof.
   - Remove implicit branch-name normalization and add previewed legacy branch migration.
   - Add exact relationship deletion, v2 receipt/schema parity, status diagnostics, dogfood package manifests, and SkillOpt cases.
@@ -324,7 +337,6 @@
   Diagnostic workflows now produce correlated evidence through both CLI JSON and MCP surfaces. Operators can run a read-only versioned remediation report that points to exact unmatched log events, preserves explicit missing-coverage work, and prevents advisor or preflight evidence from a different identified session or actor from counting as proof.
   Legacy prose can now be inspected one requirement at a time through a deterministic migration preview. The preview preserves existing code evidence, binds every extracted proposition to exact authored source, ranks project-local ontology candidates, and never emits an auto-applicable write.
   - Add the shared `kibi.requirement-proof.v2` Prolog evaluator and expose its rows, fresh receipt evidence, and summary counts through CLI and MCP coverage.
   - Persist generated symbol coordinates and symbol metadata into normal and staged RDF projections.
   - Preserve semantic-inventory JSON through mutation, sync, RDF storage, and query round trips, and refresh coordinates before extracting their manifest overlay.
@@ -346,26 +358,22 @@
 ### Patch Changes
 - 5e4e126: Agents no longer treat Kibi's CLI as an MCP fallback. MCP tools and the trusted project-local CLI are presented as peer surfaces over the same 18 operations, and agent guidance now selects whichever interface is visible and approved in the current environment. The CLI's `--input` JSON routes remain first-class for agent automation, with no preference order implied.
   - Reframe `kibi-usage` Interface Selection and the operation-access preference column to peer surfaces.
   - Update OpenCode prompt injection, enforcement, and init-kibi guidance.
   - Update the MCP init-kibi prompt and the staged-impact evidence resolution text.
   - Re-sync the Cursor and Codex skill bundles.
 - Codex and Cursor users now receive the same verified prose-to-logic guidance as the Kibi CLI. The bundled `kibi-usage` skill explains proposition coverage, typed Logic IR safety, predicate recovery, and contradiction-aware validation without relying on repository-specific release conventions.
   - Synchronize the Logic IR, fact-lane, workflow, and portable skill guidance into both agent bundles.
   - Keep the bundled skill manifests and canonical hashes aligned with the CLI public skill.
 - 5e4e126: Kibi now ships as a portable Agent Plugin alongside the existing Cursor Plugin. The open Agent Plugins standard (agent-plugins.org) packages Kibi's Agent Skills and MCP server so any compatible client — Cursor, Copilot, OpenCode, and others — loads Kibi's capabilities without client-specific adaptation. The Cursor Plugin keeps Cursor-only components (rules, commands, hooks), and both formats are listed in the same marketplace.
   - Add a committed portable Agent Plugin artifact at `agent-plugin/` with a conformant `plugin.json` manifest (plugin.schema.json 1.0.0).
   - Generate the artifact's `mcp.json` with the required `$schema` and `stdio` server type.
   - List the Agent Plugin (`plugins/kibi-agent-plugin`) in the repo marketplace alongside `kibi-cursor`.
   - Add `scripts/build-agent-plugin.ts` to regenerate the artifact and keep its skills in sync with the canonical bundle.
 - 2a85fc8: Kibi can now track whether every atomic clause in a normative requirement has a queryable logical representation. Readable prose remains intact, while stable claim keys, linked strict-property or predicate facts, and a requirement manifest expose incomplete modeling before it silently weakens contradiction detection. Exact opposite polarities over the same ground predicate now produce a contradiction.
   - Remove repository-specific release and optimizer-corpus text from `kibi-usage`.
   - Add portable clause-complete prose-to-ground-predicate/property guidance and examples.
   - Preserve logical claim and predicate-schema fields through Markdown sync.
@@ -383,7 +391,6 @@
 - 2f9073c: Kibi now ships optional guidance for recording UI and visual expectations, so agents working on a screen can discover "where things live" and cannot silently drift the layout. A prose requirement anchors the full visual description, checkable positions, alignment, and header ordering decompose into strict facts that reject conflicting writes, and relational alignment uses the built-in `visual_layout_rule` predicate. The lane is per-project: non-UI projects simply never model UI subjects, and no validation rule requires them.
   Also, `kb_status` within a long-lived MCP session now observes same-session file and KB changes instead of returning a stale cached result. Compound Prolog goals (such as the status query) are no longer cached in one-shot mode, so a status check after a source or documentation edit reports the current freshness state.
   - Add `docs/ui-requirements.md` with the three-layer UI modeling guide, payload-shaped examples, and the check workflow.
   - Point the modeling cheatsheet decision tree, agent LLM rules, and the AGENTS quick references at the new UI lane.
   - Add a self-contained `kibi-usage` skill resource (`resources/ui-requirements.md`), declare it in the skill manifest, and add a UI modeling workflow section.
@@ -395,14 +402,12 @@
 ### Minor Changes
 - b2b1792: Kibi guidance now helps agents distinguish suitable relational predicates from scalar constraints and review-only claims without replacing readable requirements. CLI, Codex, and Cursor users receive the same predicate-first decision tree and authoritative examples, reducing invented predicates and unsafe modeling.
   - Add built-in, project-local, deny, strict-scalar, ambiguity, false-positive, and ontology-gap guidance to the canonical `kibi-usage` skill.
   - Regenerate the Codex and Cursor mirrors with matching canonical hashes.
 ### Patch Changes
 - 610b5be: The improved Kibi guidance skills will ship to CLI, Codex, and Cursor users in the next package release. This keeps the canonical CLI skill bundle and the generated client-plugin mirrors aligned for downstream installs.
   - Release the canonical skills bundled by `kibi-cli`.
   - Release the generated `kibi-codex` and `kibi-cursor` skill mirrors.
@@ -411,24 +416,20 @@
 ### Minor Changes
 - a0fee4a: The Cursor plugin now supports capability-based Kibi interface selection, using visible MCP tools first and a trusted project-local CLI fallback when needed. Deterministic worktree resolution keeps both interface choices anchored to the intended repository.
   - Add MCP-first, CLI-fallback agent guidance.
   - Resolve trusted worktree runtime paths deterministically.
 ### Patch Changes
 - cafa25f: Agents can now select Kibi by available capability instead of stopping at MCP-specific guidance. The bundled skills prefer approved MCP tools, fall back safely to a project-local non-installing CLI runner, and provide executable JSON recipes plus an exact 18-operation access catalog.
   - Document every shared MCP operation's dedicated CLI route, input mode, effects, Prolog requirement, mutability, and telemetry handling.
   - Regenerate Cursor and Codex skill mirrors from the canonical capability-based source.
 - 23e815a: Agents can now keep using Kibi when MCP tools are unavailable but a trusted project-local CLI is ready. Guidance across Cursor, OpenCode, and MCP documentation now selects the interface by capability and stops for operator action only when neither safe surface is available.
   - Replace MCP-exclusive guidance with the visible-MCP, trusted-CLI JSON route, and blocked state machine.
   - Preserve direct `.kb/` access prohibitions, discovery-before-mutation, sequential writes, and completion validation gates.
 - e71f1ce: Cursor dogfood sessions now keep each linked worktree as the Kibi data workspace while launching a compatible built MCP runtime from that worktree or its primary checkout. Invalid, stale, or unrelated builds are rejected without installing packages, and Cursor hooks offer the project-local CLI only as advisory guidance after explicit workspace trust.
   - Add deterministic build, runtime, SWI-Prolog, and package-version checks to the Cursor worktree resolver.
   - Preserve an explicit `KIBI_WORKSPACE` when the MCP diagnostic launcher starts from another runtime root.
   - Track MCP capability as `observed` or `unknown` and keep hook-driven CLI fallback non-executing.
@@ -440,7 +441,6 @@
 - f1db710: Kibi check outputs now have a stable advisory diagnostics lane for auditability review signals. Operators and MCP clients can receive `qualityDiagnostics` alongside hard `violations` without advisory-only findings changing pass/fail counts or exit behavior. Existing staged impact failures, including symbol granularity violations, remain blocking. Source impact analysis now also highlights overly broad symbols, indistinguishable symbol coordinates, and mixed-purpose component/class ownership as review-only guidance.
   Technical summary:
   - Add the public `QualityDiagnostic` type with `error`, `warning`, `review`, and `info` severities plus explicit `blocking` semantics.
   - Preserve existing `violations`, `diagnostics`, and `impactDiagnostics` fields while adding MCP structured `qualityDiagnostics` output support.
   - Preserve explicitly filtered MCP `kb_check` rule semantics so advisory full-KB quality scans only run for unfiltered checks or requested impact diagnostics.
@@ -455,7 +455,6 @@
 - Kibi now gives agents source-impact feedback while they are still editing, instead of waiting for the commit hook to be the first signal. Meaningful source edits can be checked through MCP with changed-file impact diagnostics, so agents see coarse symbol ownership, stale symbol evidence, and semantic-review prompts while the source context is fresh. OpenCode, Cursor, and Codex adapters now steer agents toward that MCP-first workflow and keep CLI/hooks as the later safety net.
   Technical summary:
   - Add reusable CLI changed-file impact diagnostics and export them for MCP consumption.
   - Extend MCP `kb_check` with source-file impact options and structured impact output.
   - Update OpenCode, Cursor, and Codex guidance/hooks to request impact-enabled `kb_check` after source edits.
@@ -468,7 +467,6 @@
 - Kibi now gives agents clearer guidance for the diagnostics flow, so the release notes should reflect that the bundled usage text and MCP logging story were tightened together.
   This update also keeps the package mirrors aligned where applicable, which helps downstream plugin consumers stay in sync with the canonical guidance.
   - Hardened bundled skill guidance for kibi usage.
   - Improved MCP diagnostic logging shape and validation hints.
   - Synced packaged skill copies where they are shipped with the release.
@@ -478,14 +476,12 @@
 ### Patch Changes
 - 5d2975a: Cursor stop hooks no longer inject a long multi-line Kibi freshness reminder after every agent response. Follow-ups are now one line, and most sessions stay silent.
   - Track `kb_upsert`, `kb_delete`, and `kb_check` MCP usage during the session.
   - Emit no stop follow-up when nothing KB-relevant changed, or when `kb_check` already ran after edits.
   - Emit a short summary (`Kibi KB updated (kb_upsert).`) after KB mutations, or a single-line sync nudge when source files changed without KB activity.
   - Fix publish workflow to build and pack `kibi-cursor` tarballs before npm publish.
 - Cursor sessions now use Cursor's documented workspace root payload when deciding whether Kibi is already configured. This prevents the plugin from telling agents that Kibi needs bootstrapping just because the hook process is running from the plugin install directory instead of the actual workspace. The bootstrap reminder now names the missing `.kb/config.json` condition directly instead of implying MCP is unavailable.
   - Parse `workspace_roots` from Cursor hook payloads and prefer the first workspace root for Kibi config detection.
   - Add a regression test covering `sessionStart` without `cwd` when `workspace_roots` points at a configured workspace.
   - Reword the bootstrap reminder to describe a missing workspace config rather than generic initialization failure.
@@ -495,7 +491,6 @@
 ### Minor Changes
 - Cursor users can now install an optional Kibi adapter plugin that bundles MCP configuration, workflow rules, skills, slash commands, and advisory editor hooks. The plugin builds on the existing `kibi-cli` and `kibi-mcp` foundation without replacing them, and teams that prefer manual setup can continue configuring the local `kibi-mcp` server directly.
   - Add the publishable `kibi-cursor` package with Cursor plugin manifest assets, rules, skills, commands, hook declarations, and MCP config.
   - Add advisory hooks for bootstrap reminders, direct `.kb` edit warnings, read/write guidance, and session freshness follow-ups.
   - Wire `kibi-cursor` into workspace build, pack, release-state, publish, CI unit coverage, docs, and marketplace verification.
@@ -505,7 +500,6 @@
 ### Minor Changes
 - Cursor users can install an optional Kibi adapter plugin that bundles MCP configuration, workflow rules, skills, slash commands, and advisory editor hooks. The plugin builds on `kibi-core`, `kibi-cli`, and `kibi-mcp` without replacing them, and teams that prefer manual setup can continue configuring the local `kibi-mcp` server directly.
   - Add the publishable `kibi-cursor` package with Cursor plugin manifest assets, bundled skills, rules, commands, hook declarations, and MCP config.
   - Add a conservative hook runner with bounded session state, bootstrap reminders, direct `.kb` edit warnings, read/write guidance, and freshness follow-ups.
   - Wire `kibi-cursor` into workspace build, pack, release-state, publish, CI unit coverage, docs, and marketplace verification.

package/README.md CHANGED Viewed

@@ -10,14 +10,13 @@ Install these **before** enabling the plugin MCP server:
 | Requirement | Why |
 | --- | --- |
-| **SWI-Prolog 9+** (`swipl` on `PATH`) | Powers Kibi inference and validation |
+| **SWI-Prolog 9+** | Powers Kibi inference and validation. Bundled with `kibi-cli` on Linux (x64, arm64) and macOS; install it with `swipl` on `PATH` only on other platforms |
 | **`kibi-cli`** | Project CLI (`kibi` command) |
 | **`kibi-mcp`** | MCP server installed in the opened project; the plugin launcher resolves this package without downloading it |
 | **`kibi-core`** | Shared graph/runtime dependency |
 ```bash
 npm install --save-dev kibi-cli kibi-mcp kibi-core
-swipl --version
 npm exec -- kibi doctor
 ```
@@ -58,7 +57,10 @@ cp -r "$(npm root)/kibi-cursor" ~/.cursor/plugins/local/kibi-cursor
 The plugin bundles `mcp.json` with a thin launcher that locates and starts the
 `kibi-mcp` package installed in the opened project. The launcher starts the
 resolved child from the consumer workspace and sets `KIBI_WORKSPACE` to that
-root; it never downloads, bundles, or falls back to a global Kibi runtime:
+root; it never downloads, bundles, or falls back to a global Kibi runtime.
+The `preToolUse` hook adds `workspaceRoot` (the agent's current workspace) to
+every Kibi MCP call, so an agent working in a git worktree is answered from
+that worktree's branch. Setting `KIBI_WORKSPACE` pins one workspace instead:
 ```json
 {
@@ -105,7 +107,7 @@ agent-plugin/
 - Cursor loads the portable build directly; Cursor-only components (rules, commands, hooks) remain in the `.cursor-plugin` Cursor Plugin build.
 - Both formats are listed in the same marketplace; pick the format your client needs.
-- The portable build still requires the project-local `kibi-cli`, `kibi-mcp`, and `kibi-core` packages plus SWI-Prolog 9+ (see Prerequisites above).
+- The portable build still requires the project-local `kibi-cli`, `kibi-mcp`, and `kibi-core` packages plus SWI-Prolog 9+ (bundled on supported platforms; see Prerequisites above).
 ## Features

package/agent-plugin/plugin.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "kibi",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Repo-local, per-branch, queryable knowledge base. Portable Agent Plugin packaging Kibi's Agent Skills and MCP server.",
   "author": { "name": "Kibi" },
   "homepage": "https://github.com/Looted/kibi/blob/develop/docs/install.md",

package/agent-plugin/skills/kibi-bootstrap/SKILL.md CHANGED Viewed

@@ -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/agent-plugin/skills/kibi-bootstrap/resources/bootstrap.md CHANGED Viewed

@@ -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/agent-plugin/skills/kibi-usage/SKILL.md CHANGED Viewed

@@ -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/agent-plugin/skills/kibi-usage/resources/operation-access.md CHANGED Viewed

@@ -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/commands/kibi-bootstrap.md CHANGED Viewed

@@ -14,6 +14,9 @@ infrastructure is missing, run `kibi init` first. Then use the canonical
 planner and pass its unchanged returned `structuredContent.plan` to
 `kb_apply_plan` only after explicit approval.
-Questions come only from a `needs_context` planner result. Inspect typed apply
+Start with the skill's source interview: ask which issue trackers, wikis, and
+specs hold product intent and how authoritative each is, then pass the
+declared sources and cited intent claims to the planner. After that, further
+questions come only from a `needs_context` planner result. Inspect typed apply
 `nextActions`, finish with `kb_check` and `kb_status`, and never read or edit
 `.kb` directly.

package/dist/.cursor-plugin/plugin.json CHANGED Viewed

@@ -1,8 +1,8 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "2.1.0",
-  "description": "Optional Cursor adapter for Kibi. Requires SWI-Prolog 9+ and project-local kibi-cli, kibi-mcp, and kibi-core before the bundled MCP server can start.",
+  "version": "2.2.0",
+  "description": "Optional Cursor adapter for Kibi. Requires project-local kibi-cli, kibi-mcp, and kibi-core (SWI-Prolog is bundled on Linux and macOS) before the bundled MCP server can start.",
   "license": "AGPL-3.0-or-later",
   "author": {
     "name": "Kibi"

package/dist/commands/kibi-bootstrap.md CHANGED Viewed

@@ -14,6 +14,9 @@ infrastructure is missing, run `kibi init` first. Then use the canonical
 planner and pass its unchanged returned `structuredContent.plan` to
 `kb_apply_plan` only after explicit approval.
-Questions come only from a `needs_context` planner result. Inspect typed apply
+Start with the skill's source interview: ask which issue trackers, wikis, and
+specs hold product intent and how authoritative each is, then pass the
+declared sources and cited intent claims to the planner. After that, further
+questions come only from a `needs_context` planner result. Inspect typed apply
 `nextActions`, finish with `kb_check` and `kb_status`, and never read or edit
 `.kb` directly.

package/dist/hook-runner.d.ts CHANGED Viewed

@@ -5,11 +5,21 @@ export type CursorHookResult = {
     user_message?: string;
     agent_message?: string;
     followup_message?: string;
+    /**
+     * preToolUse only: replacement tool input. Used without `permission`, so
+     * Cursor's own approval flow is unchanged.
+     */
+    updated_input?: Record<string, unknown>;
 };
 export type HookEnvironment = {
     pluginData?: string;
     workspaceTrusted?: boolean;
 };
+/**
+ * The Kibi workspace that owns `directory`: the nearest ancestor with
+ * `.kb/manifest.json`, without crossing a `.git` boundary.
+ */
+export declare function kibiWorkspaceFor(directory: string | undefined): string | undefined;
 export declare function runHook(rawInput: unknown, environment?: HookEnvironment): Promise<CursorHookResult>;
 export declare function main(): Promise<void>;
 export declare function isInvokedAsCli(argv1: string | undefined, moduleUrl: string): boolean;

package/dist/hook-runner.js CHANGED Viewed

@@ -3,6 +3,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { stampKibiWorkspace } from "kibi-agent-core/kb-mcp-tools";
 import { preEditGuidance, readGuidance, writeGuidance } from "./guidance.js";
 import { parseHookInput, parseStdinJson, readStdin } from "./hook-input.js";
 import { addDirtyPaths, clearSessionHookState, hasGuidedPath, loadHookState, recordKbMcpTool, recordPlanDelivered, rememberGuidedPath, resolveStateDir, } from "./hook-state.js";
@@ -29,6 +30,26 @@ function hasKibiConfig(cwd) {
     }
     return fs.existsSync(path.join(cwd, ".kb", "manifest.json"));
 }
+/**
+ * The Kibi workspace that owns `directory`: the nearest ancestor with
+ * `.kb/manifest.json`, without crossing a `.git` boundary.
+ */
+export function kibiWorkspaceFor(directory) {
+    if (!directory)
+        return undefined;
+    let current = path.resolve(directory);
+    for (;;) {
+        if (fs.existsSync(path.join(current, ".kb", "manifest.json"))) {
+            return current;
+        }
+        if (fs.existsSync(path.join(current, ".git")))
+            return undefined;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
 function isEditLikeTool(toolName) {
     return toolName === undefined || editableTools.has(toolName);
 }
@@ -79,6 +100,14 @@ export async function runHook(rawInput, environment = {}) {
                 return advisory ? { additional_context: advisory } : emptyResult();
             }
         case "preToolUse": {
+            // Name the agent's workspace on every Kibi MCP call so the launcher
+            // answers from it, also for agents working in a git worktree. The
+            // per-call cwd wins over workspace_roots, which can be the window's
+            // folders rather than the agent's checkout.
+            const stamped = stampKibiWorkspace(input.toolName, input.toolInput, kibiWorkspaceFor(input.cwd ?? input.workspaceRoots?.[0]));
+            if (stamped) {
+                return { updated_input: stamped };
+            }
             const explicitPaths = extractExplicitPathFields(input.toolInput);
             const hasDirectKbEdit = isEditLikeTool(input.toolName) && explicitPaths.some(isDirectKbPath);
             if (hasDirectKbEdit) {

package/dist/skills/.canon-hash.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
-  "kibi-bootstrap/SKILL.md": "adf7ebe4985ee871e2f1d2d89fd90a20c596fa24460bfec4df525bdcebd3f1d6",
-  "kibi-bootstrap/resources/bootstrap.md": "e46d5dec74204d0652d4cba7061676c76c2f066bf6d98b073efa9fa44557be80",
+  "kibi-bootstrap/SKILL.md": "5bb63f0e5ee5ba7e60ef3dc7758ad84ee39e83ffeb46b9f038221bc48a656676",
+  "kibi-bootstrap/resources/bootstrap.md": "14531116e8a0efc69b7ccb105afebeeaa2185e720bad2d5bebadc6635598a041",
   "kibi-bootstrap/resources/branch-lifecycle.md": "c854264ce888439140883a3fc636db5e522f020dd27b30a5c1ecc4105b64ed13",
   "kibi-bootstrap/resources/operation-access.md": "b5a6a59e72d800c376e7fad79132897623c32a0ce152a1e8d73f9628b444db51",
   "kibi-bootstrap/resources/source-authoring.md": "bf296e62f69474e01797d6cb9469bf624551dca834dd188abb6e705bd96fa586",
@@ -13,12 +13,12 @@
   "kibi-traceability/resources/operation-access.md": "39f7972ab7f4ae7479e78f7072bb50e8e6c4cdf4f857425f69d2522d37db437c",
   "kibi-traceability/resources/source-authoring.md": "408c6ee2bef1b84e0194c0538ef929c26a0a617e631b2234247388140dbbdd08",
   "kibi-traceability/resources/traceability.md": "38c290a0bc71bd1692e115f22694743946e2f69630e134acfd43cee5f613fb88",
-  "kibi-usage/SKILL.md": "83567f8ead944457719e0254ad6bc1dbedda3a70d04266d2ff041a670336dcc6",
+  "kibi-usage/SKILL.md": "94982ae809de80467e5f2417ca64235dae0f81166407cdb8d0f66f322bd9efc8",
   "kibi-usage/resources/branch-lifecycle.md": "f1bf359e9826e83c548f3cd0287f8175a62456527b0132b06b3f9f74aa59b7d6",
   "kibi-usage/resources/fact-lanes.md": "7ac928cc6b3d189eee6a9cda282918677d5a222cd7ba9b7f324e6553cd3adce8",
   "kibi-usage/resources/kb-improvement.md": "17e8b6cf6a0dd43b443a2bfd92e7205d099647a5f1c75fe85413a6cea63d86c6",
   "kibi-usage/resources/logic-ir.md": "151675d0ffa813cb9e271084102a3af42de369b8f9a0c64866af0cdc4d924063",
-  "kibi-usage/resources/operation-access.md": "e8b4a3676892d2f7e2cfd708ec4ad1f41b6f296e1eb3a5ecc047f43322b4a92a",
+  "kibi-usage/resources/operation-access.md": "df8e84258f4e4855c08a9d24f7704fd540f0ea4295f5f255a4a9500a450ccf80",
   "kibi-usage/resources/proof.md": "7391046fbdeece4858b668360c60755f184af6dfedda9dbc67e2fa4574dbce7f",
   "kibi-usage/resources/relationship-directions.md": "0fdd67032c2d15299f772845fc4f807eb9435b09507bd87a5911ab33db2f143d",
   "kibi-usage/resources/source-authoring.md": "80978cea0614484292c7a70d511a3f50458f48ef976bf0675b8bb96abe9d3d36",

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

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cursor",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Kibi Cursor plugin - thin adapter for Cursor MCP integration and editor hooks",
   "type": "module",
   "main": "dist/index.js",
@@ -54,7 +54,7 @@
     }
   },
   "dependencies": {
-    "kibi-agent-core": "^0.1.0"
+    "kibi-agent-core": "^0.1.1"
   },
   "devDependencies": {
     "@types/node": "latest",

package/skills/.canon-hash.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
-  "kibi-bootstrap/SKILL.md": "adf7ebe4985ee871e2f1d2d89fd90a20c596fa24460bfec4df525bdcebd3f1d6",
-  "kibi-bootstrap/resources/bootstrap.md": "e46d5dec74204d0652d4cba7061676c76c2f066bf6d98b073efa9fa44557be80",
+  "kibi-bootstrap/SKILL.md": "5bb63f0e5ee5ba7e60ef3dc7758ad84ee39e83ffeb46b9f038221bc48a656676",
+  "kibi-bootstrap/resources/bootstrap.md": "14531116e8a0efc69b7ccb105afebeeaa2185e720bad2d5bebadc6635598a041",
   "kibi-bootstrap/resources/branch-lifecycle.md": "c854264ce888439140883a3fc636db5e522f020dd27b30a5c1ecc4105b64ed13",
   "kibi-bootstrap/resources/operation-access.md": "b5a6a59e72d800c376e7fad79132897623c32a0ce152a1e8d73f9628b444db51",
   "kibi-bootstrap/resources/source-authoring.md": "bf296e62f69474e01797d6cb9469bf624551dca834dd188abb6e705bd96fa586",
@@ -13,12 +13,12 @@
   "kibi-traceability/resources/operation-access.md": "39f7972ab7f4ae7479e78f7072bb50e8e6c4cdf4f857425f69d2522d37db437c",
   "kibi-traceability/resources/source-authoring.md": "408c6ee2bef1b84e0194c0538ef929c26a0a617e631b2234247388140dbbdd08",
   "kibi-traceability/resources/traceability.md": "38c290a0bc71bd1692e115f22694743946e2f69630e134acfd43cee5f613fb88",
-  "kibi-usage/SKILL.md": "83567f8ead944457719e0254ad6bc1dbedda3a70d04266d2ff041a670336dcc6",
+  "kibi-usage/SKILL.md": "94982ae809de80467e5f2417ca64235dae0f81166407cdb8d0f66f322bd9efc8",
   "kibi-usage/resources/branch-lifecycle.md": "f1bf359e9826e83c548f3cd0287f8175a62456527b0132b06b3f9f74aa59b7d6",
   "kibi-usage/resources/fact-lanes.md": "7ac928cc6b3d189eee6a9cda282918677d5a222cd7ba9b7f324e6553cd3adce8",
   "kibi-usage/resources/kb-improvement.md": "17e8b6cf6a0dd43b443a2bfd92e7205d099647a5f1c75fe85413a6cea63d86c6",
   "kibi-usage/resources/logic-ir.md": "151675d0ffa813cb9e271084102a3af42de369b8f9a0c64866af0cdc4d924063",
-  "kibi-usage/resources/operation-access.md": "e8b4a3676892d2f7e2cfd708ec4ad1f41b6f296e1eb3a5ecc047f43322b4a92a",
+  "kibi-usage/resources/operation-access.md": "df8e84258f4e4855c08a9d24f7704fd540f0ea4295f5f255a4a9500a450ccf80",
   "kibi-usage/resources/proof.md": "7391046fbdeece4858b668360c60755f184af6dfedda9dbc67e2fa4574dbce7f",
   "kibi-usage/resources/relationship-directions.md": "0fdd67032c2d15299f772845fc4f807eb9435b09507bd87a5911ab33db2f143d",
   "kibi-usage/resources/source-authoring.md": "80978cea0614484292c7a70d511a3f50458f48ef976bf0675b8bb96abe9d3d36",

package/skills/kibi-bootstrap/SKILL.md CHANGED Viewed

@@ -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/skills/kibi-bootstrap/resources/bootstrap.md CHANGED Viewed

@@ -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/skills/kibi-usage/SKILL.md CHANGED Viewed

@@ -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/skills/kibi-usage/resources/operation-access.md CHANGED Viewed

@@ -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.