kibi-cursor 2.0.1 → 2.1.0

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "2.0.1",
+  "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,66 @@
 # 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

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.1",
+  "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.3
+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.
@@ -160,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/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.1",
+  "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-runner.js

@@ -3,12 +3,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { readGuidance, writeGuidance } from "./guidance.js";
+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";
 import { extractKbMcpToolCall } from "./kb-mcp-tools.js";
 import { BOOTSTRAP_REMINDER, DIRECT_KB_EDIT_WARNING, interfaceAdvisory, stopFollowupMessage, } from "./messages.js";
 import { extractExplicitPathFields, isDirectKbPath, isKbFreshnessRelevantPath, isMeaningfulTrackedPath, toRepoRelativePath, } from "./path-policy.js";
+import { getSourceLinkedRequirementIds } from "./source-linked-requirements.js";
 const editableTools = new Set([
     "Edit",
     "MultiEdit",
@@ -86,7 +87,27 @@ export async function runHook(rawInput, environment = {}) {
                     agent_message: DIRECT_KB_EDIT_WARNING,
                 };
             }
-            return emptyResult();
+            const primaryPath = resolvePrimaryPath(input);
+            if (!primaryPath || !kibiReady || !isKnownEditableTool(input.toolName)) {
+                return emptyResult();
+            }
+            const relativePath = toRepoRelativePath(primaryPath, cwd);
+            const state = loadHookState(stateDir);
+            if (hasGuidedPath(state, "pre-edit", relativePath)) {
+                return emptyResult();
+            }
+            const guidance = preEditGuidance(primaryPath, {
+                cwd,
+                hasKibi: kibiReady,
+                mcpState: state.mcpState,
+                workspaceTrusted,
+                linkedRequirementIds: getSourceLinkedRequirementIds(cwd, primaryPath, stateDir),
+            });
+            if (!guidance) {
+                return emptyResult();
+            }
+            rememberGuidedPath(stateDir, "pre-edit", relativePath);
+            return { permission: "allow", agent_message: guidance };
         }
         case "beforeReadFile": {
             const primaryPath = resolvePrimaryPath(input);

package/dist/hook-state-storage.js

@@ -51,6 +51,7 @@ export function emptyHookState() {
         mcpState: "unknown",
         dirtyPaths: [],
         guidedReadPaths: [],
+        guidedPreEditPaths: [],
         guidedWritePaths: [],
         kbMutationTools: [],
         kbCheckRun: false,
@@ -164,6 +165,7 @@ function coerceHookState(value) {
         : [];
     const dirtyPaths = strings(value.dirtyPaths, normalizePath);
     const guidedReadPaths = strings(value.guidedReadPaths, normalizePath);
+    const guidedPreEditPaths = strings(value.guidedPreEditPaths, normalizePath);
     const guidedWritePaths = strings(value.guidedWritePaths, normalizePath);
     const kbMutationTools = strings(value.kbMutationTools, (entry) => entry.trim());
     const impactCheckedPaths = strings(value.impactCheckedPaths, normalizePath);
@@ -171,6 +173,7 @@ function coerceHookState(value) {
         mcpState: value.mcpState === "observed" ? "observed" : "unknown",
         dirtyPaths: [...new Set(dirtyPaths)].slice(-maxDirtyPaths),
         guidedReadPaths: [...new Set(guidedReadPaths)].slice(-maxGuidedPaths),
+        guidedPreEditPaths: [...new Set(guidedPreEditPaths)].slice(-maxGuidedPaths),
         guidedWritePaths: [...new Set(guidedWritePaths)].slice(-maxGuidedPaths),
         kbMutationTools: [...new Set(kbMutationTools)].slice(-maxKbMutationTools),
         kbCheckRun: value.kbCheckRun === true,

package/dist/hook-state.d.ts

@@ -1,9 +1,11 @@
 import type { McpState } from "./kb-mcp-tools.js";
 export { loadHookState, resolveStateDir, saveHookState, updateHookState, } from "./hook-state-storage.js";
+export type GuidedPathKind = "read" | "pre-edit" | "write";
 export type HookState = {
     mcpState: McpState;
     dirtyPaths: string[];
     guidedReadPaths: string[];
+    guidedPreEditPaths: string[];
     guidedWritePaths: string[];
     kbMutationTools: string[];
     kbCheckRun: boolean;
@@ -12,8 +14,8 @@ export type HookState = {
     planDelivered: boolean;
 };
 export declare function addDirtyPaths(stateDir: string | undefined, dirtyPaths: readonly string[]): HookState;
-export declare function rememberGuidedPath(stateDir: string | undefined, kind: "read" | "write", guidedPath: string): HookState;
-export declare function hasGuidedPath(state: HookState, kind: "read" | "write", guidedPath: string): boolean;
+export declare function rememberGuidedPath(stateDir: string | undefined, kind: GuidedPathKind, guidedPath: string): HookState;
+export declare function hasGuidedPath(state: HookState, kind: GuidedPathKind, guidedPath: string): boolean;
 export declare function recordPlanDelivered(stateDir: string | undefined): HookState;
 export declare function recordKbMcpTool(stateDir: string | undefined, toolName: string, options?: {
     impactCheckRun?: boolean;

package/dist/hook-state.js

@@ -15,6 +15,14 @@ export function rememberGuidedPath(stateDir, kind, guidedPath) {
                 guidedReadPaths: mergeStringPaths(state.guidedReadPaths, [normalized]),
             };
         }
+        if (kind === "pre-edit") {
+            return {
+                ...state,
+                guidedPreEditPaths: mergeStringPaths(state.guidedPreEditPaths, [
+                    normalized,
+                ]),
+            };
+        }
         return {
             ...state,
             guidedWritePaths: mergeStringPaths(state.guidedWritePaths, [normalized]),
@@ -22,9 +30,14 @@ export function rememberGuidedPath(stateDir, kind, guidedPath) {
     });
 }
 export function hasGuidedPath(state, kind, guidedPath) {
-    const normalized = normalizePath(guidedPath);
-    const bucket = kind === "read" ? state.guidedReadPaths : state.guidedWritePaths;
-    return bucket.includes(normalized);
+    return guidedBucket(state, kind).includes(normalizePath(guidedPath));
+}
+function guidedBucket(state, kind) {
+    if (kind === "read")
+        return state.guidedReadPaths;
+    if (kind === "pre-edit")
+        return state.guidedPreEditPaths;
+    return state.guidedWritePaths;
 }
 export function recordPlanDelivered(stateDir) {
     return updateHookState(stateDir, (state) => state.planDelivered ? state : { ...state, planDelivered: true });

package/dist/kb-mcp-tools.d.ts

@@ -1,10 +1,8 @@
-export type KbMcpToolCall = {
-    toolName: string;
-    impactCheckRun: boolean;
-    sourceFiles: string[];
-};
-export type McpState = "observed" | "unknown";
-export type KibiInterface = "mcp" | "cli" | "setup";
+import type { KbMcpToolCall as SharedKbMcpToolCall, KibiInterface as SharedKibiInterface, McpState as SharedMcpState } from "kibi-agent-core/kb-mcp-tools";
+export type KbMcpToolCall = SharedKbMcpToolCall;
+export type McpState = SharedMcpState;
+export type KibiInterface = SharedKibiInterface;
+export declare function canonicalKbToolName(toolName: string | undefined): string | undefined;
 export declare function resolveKibiInterface(mcpState: McpState, workspaceTrusted: boolean): KibiInterface;
 export declare function extractKbMcpToolCall(toolName: string | undefined, toolInput: unknown): KbMcpToolCall | undefined;
 export declare function extractKbMcpToolName(toolName: string | undefined, toolInput: unknown): string | undefined;