kibi-cursor 0.3.1 → 0.5.1

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

@@ -0,0 +1,119 @@
+# Relationship Directions
+
+## Direction Table
+
+| Relationship | Source -> Target | Semantic Meaning |
+|-------------|------------------|------------------|
+| `implements` | symbol -> req | Production code symbol owns or implements requirement behavior |
+| `specified_by` | req -> scenario | Requirement is specified by a BDD scenario |
+| `verified_by` | req/scenario -> test | Requirement or scenario is verified by a test case |
+| `validates` | test -> req/scenario | Test validates a requirement or scenario (inverse of verified_by) |
+| `executable_for` | symbol -> test | Test symbol (code) is executable code for a test entity |
+| `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` | old-req -> new-req | Old requirement is formally replaced by a new requirement |
+| `covered_by` | symbol -> test | Production symbol has test coverage evidence |
+
+## Valid Payload Examples
+
+### implements
+```yaml
+relationships:
+  - type: implements
+    from: SYM-001
+    to: REQ-001
+```
+
+### specified_by
+```yaml
+relationships:
+  - type: specified_by
+    from: REQ-001
+    to: SCEN-001
+```
+
+### verified_by
+```yaml
+relationships:
+  - type: verified_by
+    from: REQ-001
+    to: TEST-001
+```
+
+### validates
+```yaml
+relationships:
+  - type: validates
+    from: TEST-001
+    to: SCEN-001
+```
+
+### executable_for
+```yaml
+relationships:
+  - type: executable_for
+    from: SYM-test-login
+    to: TEST-001
+```
+
+### constrains
+```yaml
+relationships:
+  - type: constrains
+    from: REQ-019
+    to: FACT-USER-ROLE
+```
+
+### requires_property
+```yaml
+relationships:
+  - type: requires_property
+    from: REQ-019
+    to: FACT-LIMIT-3
+```
+
+### supersedes
+```yaml
+relationships:
+  - type: supersedes
+    from: REQ-001
+    to: REQ-001-v2
+```
+
+### covered_by
+```yaml
+relationships:
+  - type: covered_by
+    from: SYM-handler
+    to: TEST-005
+```
+
+## Invalid Test-Fact Shortcuts
+
+Do not model small behavior fixes as direct test-fact pairs. Facts describe invariants; requirements or scenarios are verified by tests.
+
+```yaml
+# WRONG: fact -> test is not a valid verified_by shape
+relationships:
+  - type: verified_by
+    from: FACT-HEADER-AVATAR-INITIAL-UPPERCASE
+    to: TEST-AVATAR-HEADER-FALLBACK
+
+# WRONG: test -> fact is not a valid validates shape
+relationships:
+  - type: validates
+    from: TEST-AVATAR-HEADER-FALLBACK
+    to: FACT-HEADER-AVATAR-INITIAL-UPPERCASE
+```
+
+Use a requirement as the verification target/source, then link that requirement to strict facts:
+
+```yaml
+relationships:
+  - type: verified_by
+    from: REQ-HEADER-AVATAR-INITIAL-UPPERCASE
+    to: TEST-AVATAR-HEADER-FALLBACK
+  - type: requires_property
+    from: REQ-HEADER-AVATAR-INITIAL-UPPERCASE
+    to: FACT-HEADER-AVATAR-INITIAL-UPPERCASE
+```

package/agent-plugin/skills/kibi-usage/resources/ui-requirements.md

@@ -0,0 +1,96 @@
+# UI / Visual Requirement Modeling
+
+Optional, per-project lane for recording what the screen should look like so UI edits cannot
+silently drift from the spec. Non-UI projects skip it entirely; no check rule requires it.
+
+## Three layers
+
+1. **Prose `req`** — the full on-screen description lives in the requirement body as the
+   searchable anchor agents discover with `kb_search` / `kb_query`.
+2. **Strict facts** — checkable visual invariants as `fact_kind: subject` (`subject_key`,
+   linked `constrains`) plus `fact_kind: property_value` (`property_key`, `operator`, typed
+   `value_*`, linked `requires_property`). Incompatible values on the same subject/property
+   from two current requirements are rejected on write unless `supersedes`.
+3. **Relational predicates** — ground `fact_kind: predicate` linked with `requires_predicate`.
+   The built-in `visual_layout_rule(subject, relation, target)` covers "X must remain visually
+   aligned with Y" (relation `aligned_with`). Other relational layout claims need a
+   project-local `predicate_schema` when the task authorizes ontology extension.
+
+Kibi enforces stated facts and links, not pixels. Freeform spatial prose is stored and
+searchable but is not machine-checked.
+
+## Button position
+
+```yaml
+id: FACT-UI-SUBMIT-REGION
+fact_kind: subject
+subject_key: settings.screen.submit_button
+```
+
+```yaml
+id: FACT-UI-SUBMIT-POSITION
+fact_kind: property_value
+subject_key: settings.screen.submit_button
+property_key: position
+operator: eq
+value_type: string
+value_string: bottom_right
+canonical_key: settings.screen.submit_button.position.eq.bottom_right
+```
+
+Link both facts from the requirement:
+
+```yaml
+id: REQ-UI-SETTINGS
+relationships:
+  - type: constrains
+    from: REQ-UI-SETTINGS
+    to: FACT-UI-SUBMIT-REGION
+  - type: requires_property
+    from: REQ-UI-SETTINGS
+    to: FACT-UI-SUBMIT-POSITION
+```
+
+A later requirement writing `position: top_left` on the same subject is rejected on write.
+
+## Header item order
+
+Use one indexed `property_key` per slot against the same subject region:
+`nav_order_1: home`, `nav_order_2: search`, `nav_order_3: profile`, each as a separate
+`property_value` fact linked with `requires_property`. This makes each slot independently
+contradiction-checkable.
+
+## Relational alignment
+
+```yaml
+id: FACT-UI-NAV-ALIGN
+fact_kind: predicate
+predicate_name: visual_layout_rule
+predicate_args: [navigation_rail, aligned_with, header]
+polarity: assert
+canonical_key: visual_layout_rule(navigation_rail,aligned_with,header)
+```
+
+Link with `requires_predicate`. An `assert`/`deny` pair over the same predicate namespace,
+name, and ordered arguments is a blocking `domain-contradictions` conflict.
+
+## UI component traceability
+
+Model the component as a `symbol` with `sourceFile` and `symbol_role: behavioral`, linked
+`implements` to the requirement, so component edits surface the visual spec in impact
+diagnostics (`symbol_semantic_review_needed`).
+
+## Workflow
+
+1. `kb_semantic_advisor` on the full description; audit or supply `clauses`.
+2. Relational clauses: `kb_suggest_predicates`, apply the predicate plan and
+   `requires_predicate`.
+3. Scalar placement/alignment/order clauses: `kb_model_requirement`, apply the strict
+   subject/property plan and `constrains` / `requires_property`.
+4. Preserve `claim_key` / `claim_text`; merge every key into the requirement
+   `logic_claims` manifest.
+5. `kb_validate_upsert`, create endpoints first, then sequential `kb_upsert`.
+6. `kb_check` with `logic-coverage`, `predicate-verifiability`, `domain-contradictions`,
+   then a final unfiltered `kb_check`.
+
+Non-UI projects: declare `has_ui: false` during bootstrap and no UI entities are proposed.

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

@@ -0,0 +1,80 @@
+# Workflows
+
+## Discovery to Validation Sequence
+
+The canonical workflow for any KB operation follows this pattern:
+
+1. **Discover**: `kb_search` with focused probes
+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
+5. **Choose per-clause lanes**: strict facts for scalar claims; `kb_suggest_predicates` for approved ground ontology relations; `kb_model_requirement` with `kibi.logic.v1` for conditions, exceptions, modalities, quantifiers, cardinality, and bounded temporal rules; observation review for ambiguity, nonlogical prose, and ontology gaps
+6. **Preflight**: `kb_validate_upsert` for every intended entity or relationship payload
+7. **Create endpoints**: validated `kb_upsert` for new entities, sequentially
+8. **Link**: validated `kb_upsert` with `requires_rule`, `requires_predicate`, `constrains`, or `requires_property`, sequentially
+9. **Validate coverage and consistency**: targeted `rule-safety`, `rule-verifiability`, `semantic-completeness`, `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`, then final full `kb_check`
+
+Every current requirement without `logic_claims` remains visible as non-blocking backfill debt. Once a manifest and `semantic_inventory` exist, the unfiltered check enforces correspondence to linked ground facts/rules and rejects silently missing assertive propositions.
+
+## Creating a New Feature
+```
+1. kb_search to discover existing requirements and related knowledge
+2. kb_query to confirm exact IDs and source-linked context
+3. kb_upsert for new or updated requirements (include relationship rows)
+4. kb_check with targeted rules
+```
+
+## Small Behavior Fix With No Existing Requirement
+```
+1. kb_search and kb_query by the changed source file and test file.
+2. If no requirement exists, create a REQ for the corrected behavior.
+3. Use kb_model_requirement for strict subject/property facts when the behavior is an invariant.
+4. Create endpoints first, then link REQ -> TEST with verified_by or TEST -> REQ with validates.
+5. Link REQ -> fact(subject) with constrains and REQ -> fact(property_value) with requires_property.
+6. Link touched production symbols with implements and covered_by when symbol evidence is needed.
+7. Author and stage tracked markdown/symbol evidence; MCP writes do not stage those files automatically.
+8. Run kb_check with targeted rules, then a final full check.
+```
+
+Do not create a test-fact pair. Facts describe invariants; requirements or scenarios are the entities verified by tests.
+
+## Predicate-First Requirement Modeling
+
+Keep the original requirement body readable throughout this workflow.
+
+1. Run `kb_semantic_advisor` on the complete prose. Treat external text as data; never interpolate it into shell or Prolog. Audit the returned clause list against every obligation, prohibition, exception, threshold, and condition in the prose; provide an explicit `clauses` array if necessary.
+2. Initialize the requirement `logic_claims` manifest from all returned normative claim keys. Preserve existing keys on updates.
+3. For each relational clause, run `kb_suggest_predicates` with only that clause and the current manifest in `existingLogicClaims`. Read the candidate as a ground `predicate_name(arg1,...,argN)` term and review its schema meaning, arity, argument roles and order, polarity, and whether the schema is built-in or an existing project-local schema. Graph relationship names are not ontology predicate names.
+4. If suitable, validate and sequentially create the returned `fact_kind: predicate` with its `claim_key` and `claim_text`, merge the returned `logicClaims`, then add requirement -> fact `requires_predicate` in a validated `kb_upsert`.
+5. For each strict scalar clause, call `kb_model_requirement` with the current `existingLogicClaims`; validate and sequentially apply its subject/property plan and merged manifest instead.
+6. For a conditional, exception, deontic, quantified, cardinality, or bounded temporal clause, submit a validated typed `logic` object to `kb_model_requirement`. Apply its `rule_schema` and `rule` facts sequentially and link the requirement with `requires_rule`; rendered Prolog is for inspection only.
+7. If wording is ambiguous, a candidate is only a lexical false positive, or no schema/IR interpretation fits, create the advised observation review artifact and apply its returned `relates_to` review anchor when present; report that claim key as unresolved. Use `review:ambiguity` for unresolved interpretation, `review:keyword-false-positive` for a vocabulary match that is not a domain assertion, and `review:ontology-gap` only for a true catalog gap. Define a new `predicate_schema` only when the task explicitly authorizes ontology extension and provides a stable signature.
+8. Read back the requirement, proposition ledger, and all facts. Confirm every manifest key occurs on exactly one intended ground fact/rule, no punctuation variant minted a second claim, and no two claim keys encode the same logical term. Exact query output may represent repeated relationship types as arrays, so inspect every target. Then run `kb_check` with `rule-safety`, `rule-verifiability`, `semantic-completeness`, `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`. Finish with an unfiltered `kb_check`.
+
+Do not treat the manifest itself as proof of grounding. The advisor keeps readiness partial while there are fewer logical edge slots than normative claims; final readback and `logic-coverage` bind those slots to exact claim keys and ground terms.
+
+Examples: built-in permission and deny claims use the suggested `permission_rule`; a project-local `commit_action` is valid only after its schema exists; session timeout is strict scalar; “better support” is ambiguous; `publishes_event` for publishing an article is a false positive; annotation anchoring without a fitting schema is an ontology gap. The authoritative payloads are in `resources/fact-lanes.md`.
+
+On resume after interruption, repeat `kb_query` for exact endpoints and apply only missing validated writes. Keep `kb_upsert` concurrency at one.
+
+## UI / Visual Requirement Modeling
+
+Optional per-project workflow for recording what the screen should look like. Non-UI projects skip this lane entirely.
+
+1. Create a prose `req` holding the full visual description; it is the searchable anchor agents discover before touching a UI file.
+2. Run `kb_semantic_advisor` on the description; audit or supply `clauses`.
+3. For relational layout clauses ("X must remain visually aligned with Y"), call `kb_suggest_predicates`, apply the returned `fact_kind: predicate` plan with `predicate_name: visual_layout_rule` and `requires_predicate`.
+4. For scalar placement, alignment, and ordering clauses, call `kb_model_requirement` and apply strict `fact_kind: subject` / `fact_kind: property_value` facts linked with `constrains` / `requires_property`. Model header order as indexed property keys (`nav_order_1`, `nav_order_2`, ...) against one subject region.
+5. Preserve `claim_key` / `claim_text` on every ground fact and merge every key into the requirement `logic_claims` manifest.
+6. Model UI components as `symbol` entities with `sourceFile` and `symbol_role: behavioral`, linked `implements` to the requirement.
+7. `kb_validate_upsert`, create endpoints first, then sequential `kb_upsert`. Run `kb_check` with `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`, then a final unfiltered `kb_check`.
+
+Incompatible values on the same subject/property from two current requirements are rejected on write; change an intentional value via a replacement requirement linked with `supersedes`. Full payloads are in `resources/ui-requirements.md`.
+
+## Fixing a Traceability Gap
+```
+1. kb_query --sourceFile <code-file> to find linked entities
+2. kb_find_gaps --type req --missing-rel specified_by to find orphan requirements
+3. kb_upsert to add missing relationship rows (sequential)
+4. kb_check with rules: ["no-dangling-refs", "symbol-traceability"]
+```

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

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "0.3.1",
+  "version": "0.5.1",
   "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/guidance.d.ts

@@ -1,2 +1,10 @@
-export declare function readGuidance(filePath: string, cwd: string | undefined, hasKibi: boolean): string | undefined;
-export declare function writeGuidance(filePath: string, cwd: string | undefined, hasKibi: boolean): string | undefined;
+import type { McpState } from "./kb-mcp-tools.js";
+export { resolveKibiInterface } from "./kb-mcp-tools.js";
+export type GuidanceContext = {
+    readonly cwd: string | undefined;
+    readonly hasKibi: boolean;
+    readonly mcpState: McpState;
+    readonly workspaceTrusted: boolean;
+};
+export declare function readGuidance(filePath: string, context: GuidanceContext): string | undefined;
+export declare function writeGuidance(filePath: string, context: GuidanceContext): string | undefined;

package/dist/guidance.js

@@ -1,38 +1,47 @@
-// implements REQ-cursor-kibi-plugin-v1
+import { interfaceAdvisory } from "./messages.js";
+// implements REQ-cursor-kibi-plugin-v1, REQ-agent-kibi-interface-selection
 import { isDocumentationTrackedPath, isMeaningfulTrackedPath, toRepoRelativePath, } from "./path-policy.js";
-export function readGuidance(filePath, cwd, hasKibi) {
-    if (!hasKibi) {
+export { resolveKibiInterface } from "./kb-mcp-tools.js";
+export function readGuidance(filePath, context) {
+    if (!context.hasKibi) {
         return undefined;
     }
-    const relativePath = toRepoRelativePath(filePath, cwd);
+    const relativePath = toRepoRelativePath(filePath, context.cwd);
     if (!isMeaningfulTrackedPath(relativePath)) {
         return undefined;
     }
-    return [
-        "Kibi read guidance: before changing this file, discover linked knowledge with Kibi MCP.",
+    const guidance = [
+        "Kibi read guidance: before changing this file, discover linked knowledge through the selected MCP or CLI JSON route.",
         `Start with kb_search, then kb_query with sourceFile="${relativePath}".`,
         "Prefer Kibi facts and requirements over long inline comments for durable knowledge.",
-    ].join("\n");
+    ];
+    const advisory = interfaceAdvisory(context.mcpState, context.workspaceTrusted);
+    return advisory ? [advisory, ...guidance].join("\n") : guidance.join("\n");
 }
-export function writeGuidance(filePath, cwd, hasKibi) {
-    if (!hasKibi) {
+export function writeGuidance(filePath, context) {
+    if (!context.hasKibi) {
         return undefined;
     }
-    const relativePath = toRepoRelativePath(filePath, cwd);
+    const relativePath = toRepoRelativePath(filePath, context.cwd);
     if (!isMeaningfulTrackedPath(relativePath)) {
         return undefined;
     }
     if (isDocumentationTrackedPath(relativePath)) {
-        return [
+        const guidance = [
             "Kibi write guidance: keep REQ, SCEN, and TEST artifacts separate.",
-            "Update KB entities through kb_upsert and finish with kb_check.",
-            "Do not edit .kb/ files directly.",
-        ].join("\n");
+            "Query before mutate. Update KB entities through kb_upsert sequentially. Run kb_check before completion.",
+            "Do not read or edit `.kb/` files directly.",
+        ];
+        const advisory = interfaceAdvisory(context.mcpState, context.workspaceTrusted);
+        return advisory ? [advisory, ...guidance].join("\n") : guidance.join("\n");
     }
-    return [
-        "Kibi write guidance: link production symbols to requirements.",
+    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.",
-    ].join("\n");
+        "Do not read or edit `.kb/` files directly. Query before mutate; run kb_upsert sequentially and kb_check before completion.",
+    ];
+    const advisory = interfaceAdvisory(context.mcpState, context.workspaceTrusted);
+    return advisory ? [advisory, ...guidance].join("\n") : guidance.join("\n");
 }

package/dist/hook-runner.d.ts

@@ -8,6 +8,7 @@ export type CursorHookResult = {
 };
 export type HookEnvironment = {
     pluginData?: string;
+    workspaceTrusted?: boolean;
 };
 export declare function runHook(rawInput: unknown, environment?: HookEnvironment): Promise<CursorHookResult>;
 export declare const hookRunnerPath: string;

package/dist/hook-runner.js

@@ -7,7 +7,7 @@ import { readGuidance, writeGuidance } from "./guidance.js";
 import { parseHookInput, parseStdinJson, readStdin } from "./hook-input.js";
 import { addDirtyPaths, clearSessionHookState, hasGuidedPath, loadHookState, recordKbMcpTool, rememberGuidedPath, resolveStateDir, } from "./hook-state.js";
 import { extractKbMcpToolCall } from "./kb-mcp-tools.js";
-import { BOOTSTRAP_REMINDER, DIRECT_KB_EDIT_WARNING, stopFollowupMessage, } from "./messages.js";
+import { BOOTSTRAP_REMINDER, DIRECT_KB_EDIT_WARNING, interfaceAdvisory, stopFollowupMessage, } from "./messages.js";
 import { extractExplicitPathFields, isDirectKbPath, isMeaningfulTrackedPath, toRepoRelativePath, } from "./path-policy.js";
 const editableTools = new Set([
     "Edit",
@@ -48,12 +48,22 @@ export async function runHook(rawInput, environment = {}) {
     const stateDir = resolveStateDir(pluginData, input.conversationId);
     const cwd = resolveWorkspaceRoot(input);
     const kibiReady = hasKibiConfig(cwd);
+    const workspaceTrusted = environment.workspaceTrusted === true;
+    const initialState = loadHookState(stateDir);
     switch (input.event) {
         case "sessionStart":
             if (!kibiReady) {
-                return { additional_context: BOOTSTRAP_REMINDER };
+                const advisory = interfaceAdvisory(initialState.mcpState, workspaceTrusted);
+                return {
+                    additional_context: advisory
+                        ? `${BOOTSTRAP_REMINDER}\n${advisory}`
+                        : BOOTSTRAP_REMINDER,
+                };
+            }
+            {
+                const advisory = interfaceAdvisory(initialState.mcpState, workspaceTrusted);
+                return advisory ? { additional_context: advisory } : emptyResult();
             }
-            return emptyResult();
         case "preToolUse": {
             const explicitPaths = extractExplicitPathFields(input.toolInput);
             const hasDirectKbEdit = isEditLikeTool(input.toolName) && explicitPaths.some(isDirectKbPath);
@@ -75,7 +85,12 @@ export async function runHook(rawInput, environment = {}) {
             if (hasGuidedPath(state, "read", relativePath)) {
                 return { permission: "allow" };
             }
-            const guidance = readGuidance(primaryPath, cwd, kibiReady);
+            const guidance = readGuidance(primaryPath, {
+                cwd,
+                hasKibi: kibiReady,
+                mcpState: state.mcpState,
+                workspaceTrusted,
+            });
             if (!guidance) {
                 return { permission: "allow" };
             }
@@ -110,7 +125,12 @@ export async function runHook(rawInput, environment = {}) {
                 if (hasGuidedPath(state, "read", relativePath)) {
                     return emptyResult();
                 }
-                const guidance = readGuidance(primaryPath, cwd, kibiReady);
+                const guidance = readGuidance(primaryPath, {
+                    cwd,
+                    hasKibi: kibiReady,
+                    mcpState: state.mcpState,
+                    workspaceTrusted,
+                });
                 if (!guidance) {
                     return emptyResult();
                 }
@@ -121,7 +141,12 @@ export async function runHook(rawInput, environment = {}) {
                 if (hasGuidedPath(state, "write", relativePath)) {
                     return emptyResult();
                 }
-                const guidance = writeGuidance(primaryPath, cwd, kibiReady);
+                const guidance = writeGuidance(primaryPath, {
+                    cwd,
+                    hasKibi: kibiReady,
+                    mcpState: state.mcpState,
+                    workspaceTrusted,
+                });
                 if (!guidance) {
                     return emptyResult();
                 }
@@ -149,7 +174,9 @@ export async function runHook(rawInput, environment = {}) {
     }
 }
 async function main() {
-    const result = await runHook(parseStdinJson(await readStdin()));
+    const result = await runHook(parseStdinJson(await readStdin()), {
+        workspaceTrusted: process.argv.includes("--trusted-workspace"),
+    });
     process.stdout.write(`${JSON.stringify(result)}\n`);
 }
 const invokedPath = process.argv[1]

package/dist/hook-state-storage.d.ts

@@ -0,0 +1,11 @@
+import type { HookState } from "./hook-state.js";
+export declare const maxDirtyPaths = 50;
+export declare const maxGuidedPaths = 100;
+export declare const maxKbMutationTools = 20;
+export declare function normalizePath(dirtyPath: string): string;
+export declare function mergeStringPaths(existingPaths: readonly string[], nextPaths: readonly string[]): string[];
+export declare function emptyHookState(): HookState;
+export declare function resolveStateDir(pluginData: string | undefined, conversationId: string | undefined): string | undefined;
+export declare function loadHookState(stateDir: string | undefined): HookState;
+export declare function saveHookState(stateDir: string | undefined, state: HookState): void;
+export declare function updateHookState(stateDir: string | undefined, updater: (state: HookState) => HookState): HookState;