kibi-cursor 2.0.0 → 2.1.0

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "2.0.0",
+  "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.",
   "license": "AGPL-3.0-or-later",
   "author": {

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # kibi-cursor
 
+## 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.
+  - Track pre-edit guidance in its own hook-state bucket so it is emitted once per path without suppressing the post-edit review.
+
+### Patch Changes
+
+- 35cd120: The ZCode, Codex, and Cursor plugins now recognize Kibi tools when the host
+  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.
+  - Stop the bundled Cursor worktree resolver from hard-coding `--diagnostic-mode`, so a shipped launcher cannot enable capture on an operator's behalf.
+  - Document the opt-in, what a row contains, and how to opt out in `docs/mcp-reference.md`.
+
+- 0128b56: Kibi now helps agents keep one shared vocabulary instead of letting every requirement invent its own. `kibi check` warns when two unrelated requirements state the same obligation. Units are compared in canonical form, so "30 min" matches "1800 s", and each warning names the exact facts involved. It also flags subject keys copied from a requirement ID, subject keys that don't follow `component.aspect`, predicates whose arguments read like prose, and entity files whose name doesn't match their ID. All of these are non-blocking warnings or info notes, so existing knowledge bases keep passing.
+
+  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.
+  - core: `ontology-quality` findings name the prose-like arguments.
+  - plugin-sdk: new `kibi.vocabulary-alignment.v1` capability (`rankSubjects`, `compareClaims`) with result validators.
+  - plugin-builtin: deterministic offline provider (IDF-weighted subject ranking and negation- and quantity-aware claim similarity).
+  - plugin-jev: Jev-backed provider. It runs in replace, augment, or shadow mode with builtin fallback, and makes network calls only when it is activated for `kb_model_requirement`. `kb_check` never calls a provider.
+  - runtime and agent adapters: regenerated skill mirrors with the naming guidance and `restates` direction docs.
+
+- Updated dependencies [5a06c03]
+  - kibi-agent-core@0.1.0
+
+## 2.0.1
+
+### 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`.
+  - Document the proof-regression workflow in `kibi-usage` 2.1.3.
+
 ## 2.0.0
 
 ### Major Changes

package/README.md

@@ -21,7 +21,7 @@ swipl --version
 npm exec -- kibi doctor
 ```
 
-Full setup: [docs/install.md](https://github.com/Looted/kibi/blob/develop/docs/install.md).
+Full setup: [installation guide](https://looted.github.io/kibi/guide/install.html#optional-cursor-plugin).
 
 Add this plugin only after the base packages work in your project.
 

package/agent-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "kibi",
-  "version": "2.0.0",
+  "version": "2.1.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-usage/SKILL.md

@@ -2,7 +2,7 @@
 id: kibi-usage
 name: Kibi Usage
 description: Use Kibi's source-first, exact-Git, migration-aware, proof-aware operations safely across MCP or the trusted local CLI, including partial completion repair.
-version: 2.1.2
+version: 2.2.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -59,7 +59,11 @@ mutability, and Prolog requirements of each operation.
 ## Safe workflow
 
 1. Always discover before you mutate: start with `kb_search`, then exact-filter with `kb_query`. Use
-   `kb_status` when branch or freshness confidence matters.
+   `kb_status` when branch or freshness confidence matters. `kb_search` ranks
+   lexically unless you pass `rankingMode: "intent-v1"`, `semanticFacets`, or
+   `sourceLocations`; use intent mode with grounded facets for conceptual
+   questions and before changing a source file, and keep lexical search for
+   literal identifiers. See `resources/workflows.md` for the mode recipe.
 2. Resolve genuine ambiguity with the human; use semantic advisor/modeling
    operations for deterministic interpretation and typed facts.
 3. Create endpoints before relationships and upsert small batches sequentially.
@@ -133,6 +137,9 @@ safe normative claims; use `observation` or `meta` for bug/workaround notes and
 tests, symbol ownership, and fresh proof-bearing receipts before claiming proof.
 For an existing product KB that needs semantic backfill, read
 `resources/kb-improvement.md`, and `resources/proof.md` for the proof workflow.
+When a proof ratchet fails, follow Debugging proof regressions in
+`resources/proof.md`: use `kibi proof explain` and compare current proof state
+to committed `proof/baseline.json` with `kibi proof impact`.
 
 ## Predicate Ontology Decision Tree
 
@@ -157,7 +164,7 @@ Represent implementation ownership with a `symbol` entity that has
 `sourceFile`, `implements` to the requirement, and `covered_by` to the test.
 Prolog `symbol-coverage` also requires the test to `validates` the requirement
 (or the requirement `verified_by` the test). `covered_by` alone is not
-enough. Do not rely on legacy `// implements REQ-xxx` comments as the
+enough. Do not rely on legacy `// implements REQ-<area>-<behavior>` comments as the
 traceability record.
 
 ## Complete Logical Coverage

package/agent-plugin/skills/kibi-usage/resources/fact-lanes.md

@@ -55,6 +55,10 @@ relationship: { type: requires_predicate, from: REQ-EDITOR-DRAFT-AUTOSAVE, to: F
 
 The project-local schema endpoint must exist before this fact is linked. When ontology extension is explicitly authorized, define it first with `fact_kind: predicate_schema`, `predicate_name`, `predicate_arity`, and equally sized `argument_names` and `argument_types`. Without an authorized stable signature, record `review:ontology-gap` instead of inventing a schema.
 
+### Closed argument vocabularies
+
+A schema can close an argument with `argument_constants` (allowed values keyed by argument name) and map older spellings with `argument_aliases`. Reuse a declared constant; `kb_upsert` rejects any other value and names the constant to use for an alias. When a genuinely new value is needed, extend `argument_constants` on the schema first. To converge existing facts, declare aliases for their spellings and let `kibi migrate` rewrite them (`predicate_schema_alignment` actions). Close only arguments with a natural shared vocabulary, such as the governed component or a severity; forcing distinct obligations into a few constants makes different requirements share one ground term.
+
 ### Deny predicate
 
 Claim: “Suspended users must not publish articles.” When `permission_rule` fits, preserve its positive schema name and encode prohibition as polarity:

package/agent-plugin/skills/kibi-usage/resources/proof.md

@@ -103,3 +103,48 @@ re-run `kibi prove` for the affected selection, then confirm `kb_status` and
 `kb_coverage` before handoff.
 
 Full reference: `docs/proving-requirements.md`.
+
+## Debugging proof regressions
+
+When a proof ratchet fails, diagnose first. Do not treat
+`proof/baseline.json` as the thing to edit.
+
+1. Do not refresh `proof/baseline.json` as the first fix.
+2. Identify the exact requirement and symbol responsible for the regression.
+3. Use Kibi proof diagnostics rather than reverse-engineering
+   `requirement_proof.pl`:
+
+   ```bash
+   kibi proof explain REQ-<id>
+   kibi proof explain SYM-<id>
+   kibi proof impact
+   ```
+
+   `kibi proof impact` compares the current Proof projection to
+   `HEAD:proof/baseline.json` (the committed ratchet snapshot, not the
+   working-tree file). It is diagnostic: fingerprint differences are reported
+   and the command exits 0 on successful evaluation. The strict ratchet remains
+   `scripts/check-proof-baseline.mjs`.
+4. For `missing_production_symbol_coverage`, inspect symbol role, owning
+   requirement, `covered_by`, candidate test scope, the requirement scenario
+   chain, and the current proof receipt. `kibi proof explain` prints those as
+   three labeled blocks so they cannot be confused:
+   `required_proofs` (TEST contract obligations), `executable_for` (test-code
+   identity), and `covered_by` (production coverage candidates with primary
+   plus optional secondary reasons).
+5. A behavioral production symbol requires qualifying behavioral/E2E evidence
+   under the current proof model.
+6. Unit coverage can satisfy structural/type-shape requirements only when the
+   symbol genuinely represents structural shape and the proof model allows it.
+7. `executable_for` identifies executable test code. Never use it on
+   production helpers merely to remove production coverage obligations.
+8. Do not trust TEST names. Resolve
+   `TEST -> proof_contract.required_proofs -> SYM -> source` and inspect what
+   the executable test actually exercises. Kibi does not infer “this TEST name
+   does not match that source file.”
+9. A passing proof producer does not automatically make every authored
+   `covered_by` relationship semantically correct.
+10. Prefer one meaningful E2E scenario covering multiple internal functions
+    plus focused unit tests for edge cases, rather than an E2E test per helper.
+11. Refresh the baseline only after a genuine intentional proof-state
+    improvement requires the ratchet snapshot to be updated.

package/agent-plugin/skills/kibi-usage/resources/relationship-directions.md

@@ -12,6 +12,7 @@
 | `constrains` | req -> fact(subject) | Requirement constrains a strict-lane domain fact |
 | `requires_property` | req -> fact(property_value) | Requirement requires a specific property value fact |
 | `supersedes` | new-req -> old-req | New requirement formally replaces an old requirement |
+| `restates` | req -> req | Requirement intentionally restates another current requirement (for example a product requirement echoed in a platform requirement); suppresses `domain-redundancy` for that pair without retiring either side |
 | `covered_by` | symbol -> test | Production symbol has test coverage evidence |
 
 ## Valid Payload Examples
@@ -20,32 +21,32 @@
 ```yaml
 relationships:
   - type: implements
-    from: SYM-001
-    to: REQ-001
+    from: SYM-operation-execute-check
+    to: REQ-cli-check
 ```
 
 ### specified_by
 ```yaml
 relationships:
   - type: specified_by
-    from: REQ-001
-    to: SCEN-001
+    from: REQ-mcp-search-discovery
+    to: SCEN-mcp-search-discovery
 ```
 
 ### verified_by
 ```yaml
 relationships:
   - type: verified_by
-    from: REQ-001
-    to: TEST-001
+    from: REQ-mcp-search-discovery
+    to: TEST-mcp-search-discovery
 ```
 
 ### validates
 ```yaml
 relationships:
   - type: validates
-    from: TEST-001
-    to: SCEN-001
+    from: TEST-mcp-search-discovery
+    to: SCEN-mcp-search-discovery
 ```
 
 ### executable_for
@@ -53,39 +54,56 @@ relationships:
 relationships:
   - type: executable_for
     from: SYM-test-login
-    to: TEST-001
+    to: TEST-mcp-search-discovery
 ```
 
 ### constrains
 ```yaml
 relationships:
   - type: constrains
-    from: REQ-019
-    to: FACT-USER-ROLE
+    from: REQ-cli-check
+    to: FACT-SUBJECT-KIBI-CHECK
 ```
 
 ### requires_property
 ```yaml
 relationships:
   - type: requires_property
-    from: REQ-019
-    to: FACT-LIMIT-3
+    from: REQ-cli-check
+    to: FACT-PROP-CHECK-FAILURE-EXIT-CODE
 ```
 
 ### supersedes
 ```yaml
 relationships:
   - type: supersedes
-    from: REQ-001-v2
-    to: REQ-001
+    from: REQ-opencode-kibi-briefing-v2
+    to: REQ-opencode-kibi-briefing-v1
 ```
 
+A `-v2` suffix is acceptable only for a direct superseding replacement like
+this one; otherwise name the new requirement by the behavior it governs.
+
+### restates
+```yaml
+# Illustrative: a product requirement echoes a platform requirement verbatim.
+relationships:
+  - type: restates
+    from: REQ-billing-invoice-retention
+    to: REQ-platform-record-retention
+```
+
+Use `restates` only when two current requirements deliberately ground the same
+logical term (same predicate, property tuple, or rule semantic key). It keeps
+both requirements current and tells `domain-redundancy` the duplication is
+intentional. If one requirement replaces the other, use `supersedes` instead.
+
 ### covered_by
 ```yaml
 relationships:
   - type: covered_by
-    from: SYM-handler
-    to: TEST-005
+    from: SYM-operation-execute-check
+    to: TEST-mcp-search-discovery
 ```
 
 ## Invalid Test-Fact Shortcuts

package/agent-plugin/skills/kibi-usage/resources/source-authoring.md

@@ -29,3 +29,39 @@ Cancellation follows the same rule: wait for the terminal journal state. A
 pre-commit rollback is retryable, a committed source with a failed derivative
 is repairable, and an indeterminate outcome is non-retryable until its recovery
 action resolves the journal.
+
+## Naming entities
+
+Name every entity by what it governs, the way you would name a source file.
+Never choose "the next number": parallel branches pick the same next number and
+collide even when they touch unrelated behavior.
+
+- Use `<TYPE>-<area>-<behavior>` in kebab-case, with the type prefix kept
+  uppercase: `REQ-cli-gc`, `SCEN-mcp-search-discovery`,
+  `TEST-mcp-search-discovery`, `ADR-capability-plugins-v1`,
+  `EVT-exact-branch-store-ensure`, and a flag named after its gate such as
+  `FLAG-scip-symbol-extraction`.
+- The filename stem equals the frontmatter `id`
+  (`.kb/requirements/REQ-cli-gc.md` has `id: REQ-cli-gc`). Always set `id`
+  explicitly; a missing `id` falls back to a path-and-title hash that changes
+  when the file is renamed.
+- Before creating an entity, `kb_search` the area. If an existing entity already
+  covers the behavior, update it, or create a replacement and link it with
+  `supersedes`. A `-v2` suffix is acceptable only for that direct superseding
+  replacement.
+- A name collision with another branch usually means the same work was done
+  twice. Reconcile the two entities; do not rename one of them to dodge the
+  collision.
+- The area prefix is for humans. Whether two requirements are about the same
+  thing is decided by their facts: a shared `subject_key` and identical
+  predicate or property signatures, which `domain-redundancy` and
+  `domain-contradictions` compare deterministically. Reuse existing subject keys
+  (dotted `component.aspect[.sub]`, lowercase snake segments such as
+  `kibi.cli.check.staged`) instead of deriving a subject from the requirement
+  ID.
+
+`entity-id-style` reports new purely numeric IDs (`REQ-123`) and IDs whose
+filename stem differs from `id` as non-blocking quality diagnostics. Legacy
+numbered entities created before the naming standard are grandfathered and are
+not renamed, because code comments such as `// implements REQ-003` still
+reference them.

package/agent-plugin/skills/kibi-usage/resources/workflows.md

@@ -33,11 +33,62 @@ surfaces are a release defect: require a new package version and label any
 project override temporary. This skill never selects a package manager or
 edits dependency configuration.
 
+## Choosing a discovery mode
+
+`kb_search` is not one behavior. It selects deterministic intent ranking when
+you pass `rankingMode: "intent-v1"`, `semanticFacets`, or `sourceLocations`,
+and legacy lexical ranking otherwise. Naming the tool is not enough; the inputs
+decide the path.
+
+- **Exact identity** — you already know the ID. Use `kb_query`, not search.
+- **Literal token** — a symbol, file, or error string that appears verbatim.
+  Use lexical `kb_search` and keep the query close to the literal text.
+- **Conceptual or behavioral** — "how does checkout handle a declined card".
+  Use intent mode and ground it in what you actually know:
+
+```json
+{
+  "query": "declined card during checkout",
+  "rankingMode": "intent-v1",
+  "semanticFacets": {
+    "actors": ["shopper"],
+    "actions": ["pay"],
+    "objects": ["card"],
+    "constraints": ["declined"]
+  }
+}
+```
+
+- **Before changing code** — pass the file you are about to edit as a source
+  location, so results are matched against source-linked symbols and return
+  source evidence:
+
+```json
+{
+  "query": "checkout total rounding",
+  "rankingMode": "intent-v1",
+  "sourceLocations": [{ "path": "src/checkout.ts", "symbol": "computeTotal" }]
+}
+```
+
+Supply facets only from the request, the code, or prior results. Inventing
+facets fabricates evidence and biases ranking. Intent mode abstains below
+`minScore` instead of returning weak matches; an abstention is an explicit
+no-answer, so widen the query or drop to lexical search rather than treating it
+as "nothing exists". There is no target percentage of intent-mode calls — a
+literal identifier lookup is still best served lexically.
+
+Results are summaries by default: identifying metadata, score, reasons, and a
+snippet. Read them to pick candidates, then `kb_query` those IDs for full
+bodies, or pass `fields: "full"` when you genuinely need every body. Extract
+the relevant existing constraints and decisions from the response before
+planning a behavior change; a search receipt is not comprehension.
+
 ## Discovery to Validation Sequence
 
 The canonical workflow for any KB operation follows this pattern:
 
-1. **Discover**: `kb_search` with focused probes
+1. **Discover**: `kb_search` with focused probes; pick the mode above
 2. **Confirm**: `kb_query` for exact IDs and state
 3. **Inspect**: `kb_status` when freshness matters
 4. **Decompose**: `kb_semantic_advisor` on the complete normative prose; verify or supply every atomic clause

package/bin/launch-kibi-mcp.mjs

@@ -362,7 +362,14 @@ export function launchKibiMcp(
     [projectLocal.binPath, ...childArgs],
     {
       cwd: workspaceRoot,
-      env: { ...env, KIBI_WORKSPACE: workspaceRoot },
+      env: {
+        ...env,
+        KIBI_WORKSPACE: workspaceRoot,
+        // Identify the host on usage rows. This never enables telemetry;
+        // KIBI_DIAGNOSTIC_MODE stays the operator's explicit opt-in and is
+        // passed through untouched.
+        KIBI_MCP_HOST: "cursor",
+      },
       stdio: ["inherit", "inherit", "inherit"],
     },
   );

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

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "2.0.0",
+  "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.",
   "license": "AGPL-3.0-or-later",
   "author": {

package/dist/bin/launch-kibi-mcp.mjs

@@ -362,7 +362,14 @@ export function launchKibiMcp(
     [projectLocal.binPath, ...childArgs],
     {
       cwd: workspaceRoot,
-      env: { ...env, KIBI_WORKSPACE: workspaceRoot },
+      env: {
+        ...env,
+        KIBI_WORKSPACE: workspaceRoot,
+        // Identify the host on usage rows. This never enables telemetry;
+        // KIBI_DIAGNOSTIC_MODE stays the operator's explicit opt-in and is
+        // passed through untouched.
+        KIBI_MCP_HOST: "cursor",
+      },
       stdio: ["inherit", "inherit", "inherit"],
     },
   );

package/dist/guidance.d.ts

@@ -5,6 +5,17 @@ export type GuidanceContext = {
     readonly hasKibi: boolean;
     readonly mcpState: McpState;
     readonly workspaceTrusted: boolean;
+    /** Requirements the edited file already owns, when the manifest knows them. */
+    readonly linkedRequirementIds?: readonly string[];
 };
 export declare function readGuidance(filePath: string, context: GuidanceContext): string | undefined;
+/**
+ * Guidance emitted before an edit is written.
+ *
+ * The post-edit and stop messages can only ask for repair once the code is
+ * already changed. This is the one point where retrieval can still inform the
+ * change, so it names the requirements the file already implements and asks
+ * for them to be read before the edit rather than reconciled after it.
+ */
+export declare function preEditGuidance(filePath: string, context: GuidanceContext): string | undefined;
 export declare function writeGuidance(filePath: string, context: GuidanceContext): string | undefined;

package/dist/guidance.js

@@ -18,6 +18,40 @@ export function readGuidance(filePath, context) {
     const advisory = interfaceAdvisory(context.mcpState, context.workspaceTrusted);
     return advisory ? [advisory, ...guidance].join("\n") : guidance.join("\n");
 }
+/**
+ * Guidance emitted before an edit is written.
+ *
+ * The post-edit and stop messages can only ask for repair once the code is
+ * already changed. This is the one point where retrieval can still inform the
+ * change, so it names the requirements the file already implements and asks
+ * for them to be read before the edit rather than reconciled after it.
+ */
+export function preEditGuidance(filePath, context) {
+    if (!context.hasKibi) {
+        return undefined;
+    }
+    const relativePath = toRepoRelativePath(filePath, context.cwd);
+    if (!isMeaningfulTrackedPath(relativePath)) {
+        return undefined;
+    }
+    if (isDocumentationTrackedPath(relativePath)) {
+        return undefined;
+    }
+    const linkedRequirements = context.linkedRequirementIds ?? [];
+    const guidance = linkedRequirements.length > 0
+        ? [
+            `Kibi pre-edit guidance: ${relativePath} already implements ${linkedRequirements.join(", ")}.`,
+            `Read those requirements with kb_query before changing behavior here, and widen with kb_query({sourceFile:"${relativePath}"}) for scenarios and tests.`,
+            "If the change contradicts an existing requirement, resolve that in Kibi before writing the edit.",
+        ]
+        : [
+            `Kibi pre-edit guidance: ${relativePath} has no linked requirement in the symbol manifest.`,
+            `Discover existing constraints with kb_search, then kb_query({sourceFile:"${relativePath}"}), before changing behavior here.`,
+            "Record the requirement this change serves rather than leaving the symbol unowned.",
+        ];
+    const advisory = interfaceAdvisory(context.mcpState, context.workspaceTrusted);
+    return advisory ? [advisory, ...guidance].join("\n") : guidance.join("\n");
+}
 export function writeGuidance(filePath, context) {
     if (!context.hasKibi) {
         return undefined;
@@ -35,12 +69,12 @@ export function writeGuidance(filePath, context) {
         const advisory = interfaceAdvisory(context.mcpState, context.workspaceTrusted);
         return advisory ? [advisory, ...guidance].join("\n") : guidance.join("\n");
     }
+    // Retrieval is asked for before the edit; this message stays scoped to the
+    // impact review that only becomes possible once the change exists.
     const guidance = [
-        "Kibi write guidance: use the selected MCP or CLI JSON route to link production symbols to requirements.",
-        `After editing, run kb_check({sourceFiles:["${relativePath}"], includeImpactDiagnostics:true, includeWorkingTreeDiff:true}) for symbol granularity and semantic review of linked requirements/tests.`,
-        `After editing, resolve freshness with kb_search/kb_query for sourceFile="${relativePath}".`,
-        "Prefer symbol manifest + executable_for or // implements REQ-xxx for traceability.",
-        "Do not read or edit `.kb/` files directly. Query before mutate; run kb_upsert sequentially and kb_check before completion.",
+        `Kibi impact review: run kb_check({sourceFiles:["${relativePath}"], includeImpactDiagnostics:true, includeWorkingTreeDiff:true}) while this edit is fresh.`,
+        "Check symbol granularity and whether linked requirements, scenarios, and tests still cover the changed behavior.",
+        "Prefer symbol manifest + executable_for or // implements REQ-<area>-<behavior> for traceability.",
     ];
     const advisory = interfaceAdvisory(context.mcpState, context.workspaceTrusted);
     return advisory ? [advisory, ...guidance].join("\n") : guidance.join("\n");

package/dist/hook-input.js

@@ -1,4 +1,10 @@
+// rationale: parseHookInput degrades every non-record to { event: "" };
+// dropping the typeof check still yields the same parse for all inputs.
+// Stryker disable next-line ConditionalExpression
 function isRecord(value) {
+    // rationale: parseHookInput degrades every non-record to { event: "" };
+    // dropping the typeof check still yields the same parse for all inputs.
+    // Stryker disable next-line ConditionalExpression
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function readString(record, keys) {
@@ -25,9 +31,6 @@ function readStringArray(record, keys) {
 }
 function normalizeEventName(event) {
     const trimmed = event.trim();
-    if (trimmed.length === 0) {
-        return "";
-    }
     return trimmed.charAt(0).toLowerCase() + trimmed.slice(1);
 }
 function parseStopStatus(value) {
@@ -92,7 +95,7 @@ export function parseHookInput(input) {
 export async function readStdin() {
     const chunks = [];
     for await (const chunk of process.stdin) {
-        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+        chunks.push(Buffer.from(chunk));
     }
     return Buffer.concat(chunks).toString("utf8");
 }