kibi-cursor 0.3.1 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/.cursor-plugin/plugin.json +1 -1
  2. package/CHANGELOG.md +92 -0
  3. package/README.md +21 -4
  4. package/agent-plugin/mcp.json +10 -0
  5. package/agent-plugin/plugin.json +11 -0
  6. package/agent-plugin/skills/init-kibi/SKILL.md +62 -0
  7. package/agent-plugin/skills/kibi-freshness/SKILL.md +44 -0
  8. package/agent-plugin/skills/kibi-traceability/SKILL.md +54 -0
  9. package/agent-plugin/skills/kibi-usage/SKILL.md +270 -0
  10. package/agent-plugin/skills/kibi-usage/resources/fact-lanes.md +235 -0
  11. package/agent-plugin/skills/kibi-usage/resources/logic-ir.md +43 -0
  12. package/agent-plugin/skills/kibi-usage/resources/operation-access.md +44 -0
  13. package/agent-plugin/skills/kibi-usage/resources/relationship-directions.md +119 -0
  14. package/agent-plugin/skills/kibi-usage/resources/ui-requirements.md +96 -0
  15. package/agent-plugin/skills/kibi-usage/resources/workflows.md +80 -0
  16. package/dist/.cursor-plugin/plugin.json +1 -1
  17. package/dist/guidance.d.ts +10 -2
  18. package/dist/guidance.js +26 -17
  19. package/dist/hook-runner.d.ts +1 -0
  20. package/dist/hook-runner.js +34 -7
  21. package/dist/hook-state-storage.d.ts +11 -0
  22. package/dist/hook-state-storage.js +187 -0
  23. package/dist/hook-state.d.ts +3 -4
  24. package/dist/hook-state.js +6 -206
  25. package/dist/kb-mcp-tools.d.ts +3 -0
  26. package/dist/kb-mcp-tools.js +6 -0
  27. package/dist/messages.d.ts +4 -2
  28. package/dist/messages.js +14 -2
  29. package/dist/rules/kibi-workflow.mdc +3 -3
  30. package/dist/skills/.canon-hash.json +12 -0
  31. package/dist/skills/init-kibi/SKILL.md +50 -11
  32. package/dist/skills/kibi-freshness/SKILL.md +32 -10
  33. package/dist/skills/kibi-traceability/SKILL.md +41 -11
  34. package/dist/skills/kibi-usage/SKILL.md +149 -97
  35. package/dist/skills/kibi-usage/resources/fact-lanes.md +235 -0
  36. package/dist/skills/kibi-usage/resources/logic-ir.md +43 -0
  37. package/dist/skills/kibi-usage/resources/operation-access.md +44 -0
  38. package/dist/skills/kibi-usage/resources/relationship-directions.md +119 -0
  39. package/dist/skills/kibi-usage/resources/ui-requirements.md +96 -0
  40. package/dist/skills/kibi-usage/resources/workflows.md +80 -0
  41. package/package.json +3 -2
  42. package/rules/kibi-workflow.mdc +3 -3
  43. package/skills/.canon-hash.json +12 -0
  44. package/skills/init-kibi/SKILL.md +50 -11
  45. package/skills/kibi-freshness/SKILL.md +32 -10
  46. package/skills/kibi-traceability/SKILL.md +41 -11
  47. package/skills/kibi-usage/SKILL.md +149 -97
  48. package/skills/kibi-usage/resources/fact-lanes.md +235 -0
  49. package/skills/kibi-usage/resources/logic-ir.md +43 -0
  50. package/skills/kibi-usage/resources/operation-access.md +44 -0
  51. package/skills/kibi-usage/resources/relationship-directions.md +119 -0
  52. package/skills/kibi-usage/resources/ui-requirements.md +96 -0
  53. package/skills/kibi-usage/resources/workflows.md +80 -0
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "kibi-cursor",
3
3
  "displayName": "Kibi",
4
- "version": "0.3.1",
4
+ "version": "0.5.1",
5
5
  "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.",
6
6
  "license": "AGPL-3.0-or-later",
7
7
  "author": {
package/CHANGELOG.md CHANGED
@@ -1,5 +1,97 @@
1
1
  # kibi-cursor
2
2
 
3
+ ## 0.5.1
4
+
5
+ ### Patch Changes
6
+
7
+ - 5e4e126: Agents no longer treat Kibi's CLI as an MCP fallback. MCP tools and the trusted project-local CLI are presented as peer surfaces over the same 18 operations, and agent guidance now selects whichever interface is visible and approved in the current environment. The CLI's `--input` JSON routes remain first-class for agent automation, with no preference order implied.
8
+
9
+ - Reframe `kibi-usage` Interface Selection and the operation-access preference column to peer surfaces.
10
+ - Update OpenCode prompt injection, enforcement, and init-kibi guidance.
11
+ - Update the MCP init-kibi prompt and the staged-impact evidence resolution text.
12
+ - Re-sync the Cursor and Codex skill bundles.
13
+
14
+ - Codex and Cursor users now receive the same verified prose-to-logic guidance as the Kibi CLI. The bundled `kibi-usage` skill explains proposition coverage, typed Logic IR safety, predicate recovery, and contradiction-aware validation without relying on repository-specific release conventions.
15
+
16
+ - Synchronize the Logic IR, fact-lane, workflow, and portable skill guidance into both agent bundles.
17
+ - Keep the bundled skill manifests and canonical hashes aligned with the CLI public skill.
18
+
19
+ - 5e4e126: Kibi now ships as a portable Agent Plugin alongside the existing Cursor Plugin. The open Agent Plugins standard (agent-plugins.org) packages Kibi's Agent Skills and MCP server so any compatible client — Cursor, Copilot, OpenCode, and others — loads Kibi's capabilities without client-specific adaptation. The Cursor Plugin keeps Cursor-only components (rules, commands, hooks), and both formats are listed in the same marketplace.
20
+
21
+ - Add a committed portable Agent Plugin artifact at `agent-plugin/` with a conformant `plugin.json` manifest (plugin.schema.json 1.0.0).
22
+ - Generate the artifact's `mcp.json` with the required `$schema` and `stdio` server type.
23
+ - List the Agent Plugin (`plugins/kibi-agent-plugin`) in the repo marketplace alongside `kibi-cursor`.
24
+ - Add `scripts/build-agent-plugin.ts` to regenerate the artifact and keep its skills in sync with the canonical bundle.
25
+
26
+ - 2a85fc8: Kibi can now track whether every atomic clause in a normative requirement has a queryable logical representation. Readable prose remains intact, while stable claim keys, linked strict-property or predicate facts, and a requirement manifest expose incomplete modeling before it silently weakens contradiction detection. Exact opposite polarities over the same ground predicate now produce a contradiction.
27
+
28
+ - Remove repository-specific release and optimizer-corpus text from `kibi-usage`.
29
+ - Add portable clause-complete prose-to-ground-predicate/property guidance and examples.
30
+ - Preserve logical claim and predicate-schema fields through Markdown sync.
31
+ - Add semantic-advisor clause inventories, merged claim manifests, and the `logic-coverage` check.
32
+ - Enable manifest validation by default and report every current unmanifested requirement as explicit backfill debt.
33
+ - Detect exact `assert`/`deny` conflicts over the same ground predicate.
34
+ - Normalize trailing clause punctuation so formatting variants share one claim identity.
35
+ - Enforce a one-claim/one-ground-fact mapping and reject duplicate logical terms masquerading as separate coverage.
36
+ - Preserve every target when exact query results contain repeated relationship types.
37
+ - Keep semantic-advisor readiness partial until every normative claim has a distinct logical grounding slot.
38
+ - Drain machine-readable CLI output before the explicit process exit so large results are complete without leaving runtime handles alive.
39
+ - Preserve and enforce claim-key patterns, uniqueness, and paired provenance through MCP schema registration.
40
+ - Synchronize the corrected skill into the Codex and Cursor bundles.
41
+
42
+ - 2f9073c: Kibi now ships optional guidance for recording UI and visual expectations, so agents working on a screen can discover "where things live" and cannot silently drift the layout. A prose requirement anchors the full visual description, checkable positions, alignment, and header ordering decompose into strict facts that reject conflicting writes, and relational alignment uses the built-in `visual_layout_rule` predicate. The lane is per-project: non-UI projects simply never model UI subjects, and no validation rule requires them.
43
+
44
+ Also, `kb_status` within a long-lived MCP session now observes same-session file and KB changes instead of returning a stale cached result. Compound Prolog goals (such as the status query) are no longer cached in one-shot mode, so a status check after a source or documentation edit reports the current freshness state.
45
+
46
+ - Add `docs/ui-requirements.md` with the three-layer UI modeling guide, payload-shaped examples, and the check workflow.
47
+ - Point the modeling cheatsheet decision tree, agent LLM rules, and the AGENTS quick references at the new UI lane.
48
+ - Add a self-contained `kibi-usage` skill resource (`resources/ui-requirements.md`), declare it in the skill manifest, and add a UI modeling workflow section.
49
+ - Synchronize the updated `kibi-usage` skill into the Codex and Cursor bundles.
50
+ - Keep compound Prolog goals out of the one-shot query cache so `kb_status` reports fresh state after same-session writes.
51
+
52
+ ## 0.5.0
53
+
54
+ ### Minor Changes
55
+
56
+ - b2b1792: Kibi guidance now helps agents distinguish suitable relational predicates from scalar constraints and review-only claims without replacing readable requirements. CLI, Codex, and Cursor users receive the same predicate-first decision tree and authoritative examples, reducing invented predicates and unsafe modeling.
57
+
58
+ - Add built-in, project-local, deny, strict-scalar, ambiguity, false-positive, and ontology-gap guidance to the canonical `kibi-usage` skill.
59
+ - Regenerate the Codex and Cursor mirrors with matching canonical hashes.
60
+
61
+ ### Patch Changes
62
+
63
+ - 610b5be: The improved Kibi guidance skills will ship to CLI, Codex, and Cursor users in the next package release. This keeps the canonical CLI skill bundle and the generated client-plugin mirrors aligned for downstream installs.
64
+
65
+ - Release the canonical skills bundled by `kibi-cli`.
66
+ - Release the generated `kibi-codex` and `kibi-cursor` skill mirrors.
67
+
68
+ ## 0.4.0
69
+
70
+ ### Minor Changes
71
+
72
+ - a0fee4a: The Cursor plugin now supports capability-based Kibi interface selection, using visible MCP tools first and a trusted project-local CLI fallback when needed. Deterministic worktree resolution keeps both interface choices anchored to the intended repository.
73
+
74
+ - Add MCP-first, CLI-fallback agent guidance.
75
+ - Resolve trusted worktree runtime paths deterministically.
76
+
77
+ ### Patch Changes
78
+
79
+ - cafa25f: Agents can now select Kibi by available capability instead of stopping at MCP-specific guidance. The bundled skills prefer approved MCP tools, fall back safely to a project-local non-installing CLI runner, and provide executable JSON recipes plus an exact 18-operation access catalog.
80
+
81
+ - Document every shared MCP operation's dedicated CLI route, input mode, effects, Prolog requirement, mutability, and telemetry handling.
82
+ - Regenerate Cursor and Codex skill mirrors from the canonical capability-based source.
83
+
84
+ - 23e815a: Agents can now keep using Kibi when MCP tools are unavailable but a trusted project-local CLI is ready. Guidance across Cursor, OpenCode, and MCP documentation now selects the interface by capability and stops for operator action only when neither safe surface is available.
85
+
86
+ - Replace MCP-exclusive guidance with the visible-MCP, trusted-CLI JSON route, and blocked state machine.
87
+ - Preserve direct `.kb/` access prohibitions, discovery-before-mutation, sequential writes, and completion validation gates.
88
+
89
+ - e71f1ce: Cursor dogfood sessions now keep each linked worktree as the Kibi data workspace while launching a compatible built MCP runtime from that worktree or its primary checkout. Invalid, stale, or unrelated builds are rejected without installing packages, and Cursor hooks offer the project-local CLI only as advisory guidance after explicit workspace trust.
90
+
91
+ - Add deterministic build, runtime, SWI-Prolog, and package-version checks to the Cursor worktree resolver.
92
+ - Preserve an explicit `KIBI_WORKSPACE` when the MCP diagnostic launcher starts from another runtime root.
93
+ - Track MCP capability as `observed` or `unknown` and keep hook-driven CLI fallback non-executing.
94
+
3
95
  ## 0.3.1
4
96
 
5
97
  ### Patch Changes
package/README.md CHANGED
@@ -25,11 +25,13 @@ Full setup: [docs/install.md](https://github.com/Looted/kibi/blob/develop/docs/i
25
25
 
26
26
  Add this plugin only after the base packages work in your project.
27
27
 
28
+ **Git worktrees:** the published plugin MCP entry (`npx --no-install kibi-mcp`) needs `kibi-mcp` resolvable from that worktree's `node_modules` (run install there). For this monorepo's dogfood path, prefer project `.cursor/mcp.json`, which can fall back to the primary checkout's built MCP — see [DEV.md](./DEV.md#linked-worktrees).
29
+
28
30
  ## Installation
29
31
 
30
32
  ### Cursor Marketplace (recommended)
31
33
 
32
- Submit or install from the Kibi repository marketplace at `.cursor-plugin/marketplace.json`, which points at `./plugins/kibi-cursor`.
34
+ Submit or install from the Kibi repository marketplace at `.cursor-plugin/marketplace.json`, which points at `./plugins/kibi-cursor` (Cursor Plugin) and `./plugins/kibi-agent-plugin` (portable Agent Plugin). Cursor detects the format from the plugin manifest, so both install from the same marketplace.
33
35
 
34
36
  For local testing before marketplace publication, copy a real directory tree into Cursor's user-plugins folder. Symlinks are rejected when the target lives outside `plugins/local` (common on WSL):
35
37
 
@@ -81,11 +83,26 @@ Manual MCP fallback (no plugin install required):
81
83
  }
82
84
  ```
83
85
 
86
+ ## Portable Agent Plugin (Agent Plugins standard)
87
+
88
+ `kibi-cursor` also ships a portable [Agent Plugins](https://agent-plugins.org) build at `agent-plugin/`. The Agent Plugins open standard (v1.0.0) packages Agent Skills and MCP servers for any compatible client — Cursor, Copilot, OpenCode, and others — so the same Kibi capabilities load without client-specific adaptation.
89
+
90
+ ```
91
+ agent-plugin/
92
+ ├── plugin.json # agent-plugins.org/schemas/1.0.0/plugin.schema.json
93
+ ├── skills/ # canonical Kibi Agent Skills (kibi-usage, init-kibi, ...)
94
+ └── mcp.json # agent-plugins.org/schemas/1.0.0/mcp.schema.json (stdio kibi-mcp)
95
+ ```
96
+
97
+ - Cursor loads the portable build directly; Cursor-only components (rules, commands, hooks) remain in the `.cursor-plugin` Cursor Plugin build.
98
+ - Both formats are listed in the same marketplace; pick the format your client needs.
99
+ - The portable build still requires the project-local `kibi-cli`, `kibi-mcp`, and `kibi-core` packages plus SWI-Prolog 9+ (see Prerequisites above).
100
+
84
101
  ## Features
85
102
 
86
103
  ### Discovery-first rules and skills
87
104
 
88
- - **Rules**: always-on MCP workflow guidance plus optional traceability rules for source files.
105
+ - **Rules**: always-on capability-based workflow guidance plus optional traceability rules for source files.
89
106
  - **Skills**: `kibi-usage`, `init-kibi`, `kibi-freshness`, and `kibi-traceability`.
90
107
  - **Commands**: `/init-kibi` documents the `kb_autopilot_generate` bootstrap workflow.
91
108
 
@@ -104,14 +121,14 @@ Hooks are warning-only and never replace MCP/CLI behavior:
104
121
  Per the thin-adapter architecture, `kibi-cursor` does not:
105
122
 
106
123
  - Own KB storage, parsing, or validation
107
- - Run background `kibi sync` or CLI `kibi check` (use git hooks and MCP tools; for source edits, use impact-enabled MCP `kb_check` first)
124
+ - Run background `kibi sync` or CLI `kibi check` from hooks (agents select visible MCP tools or trusted project-local CLI JSON routes; for source edits, use impact-enabled `kb_check` first)
108
125
  - Block agent actions in advisory mode
109
126
 
110
127
  ## Architecture
111
128
 
112
129
  `kibi-cursor` is a thin bridge layer:
113
130
 
114
- - **Agent-visible guidance**: public MCP tools (`kb_search`, `kb_query`, `kb_upsert`, impact-enabled `kb_check`, etc.) and the `/init-kibi` command
131
+ - **Agent-visible guidance**: visible public MCP tools or trusted project-local CLI JSON routes (`--input`), plus a blocked/operator state when neither is available
115
132
  - **Editor-specific value**: Cursor hooks for read/write reminders and session freshness follow-ups
116
133
  - **Foundation**: `kibi-core`, `kibi-cli`, and `kibi-mcp` remain required for project-local operations
117
134
 
@@ -0,0 +1,10 @@
1
+ {
2
+ "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
3
+ "mcpServers": {
4
+ "kibi": {
5
+ "type": "stdio",
6
+ "command": "npx",
7
+ "args": ["--no-install", "kibi-mcp"]
8
+ }
9
+ }
10
+ }
@@ -0,0 +1,11 @@
1
+ {
2
+ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
+ "name": "kibi",
4
+ "version": "0.5.1",
5
+ "description": "Repo-local, per-branch, queryable knowledge base. Portable Agent Plugin packaging Kibi's Agent Skills and MCP server.",
6
+ "author": { "name": "Kibi" },
7
+ "homepage": "https://github.com/Looted/kibi/blob/develop/docs/install.md",
8
+ "repository": "https://github.com/Looted/kibi.git",
9
+ "license": "AGPL-3.0-or-later",
10
+ "keywords": ["kibi", "mcp", "knowledge-base", "traceability", "swi-prolog"]
11
+ }
@@ -0,0 +1,62 @@
1
+ ---
2
+ id: init-kibi
3
+ name: init-kibi
4
+ description: Bootstrap and model knowledge safely using approved Kibi MCP initialization and mutation workflow.
5
+ version: 1.0.0
6
+ kibiCompatibility: "*"
7
+ tags:
8
+ - kibi
9
+ - mcp
10
+ - bootstrap
11
+ - agent-guidance
12
+ ---
13
+ ## Goal
14
+
15
+ Set up or refresh Kibi knowledge for the current branch through approved Kibi interfaces only. Maintain source-file traceability for every repository-backed claim, and require explicit operator approval before any mutation.
16
+
17
+ ## Interface Selection
18
+
19
+ 1. If approved Kibi MCP tools are visible, use the MCP route.
20
+ 2. Otherwise, in a trusted workspace, use the canonical project-local CLI fallback: `npx --no-install kibi ...` or `bunx --no-install kibi ...`.
21
+ 3. If neither approved MCP tools nor the project-local CLI are available, stop and tell the operator to enable or install Kibi for this workspace.
22
+ 4. Never use a global fallback, an installing runner, or any route outside the approved Kibi interface.
23
+
24
+ Use `kibi-usage/resources/operation-access.md` for the exact operation-to-route mapping. The CLI preview route accepts the same JSON object as `kb_autopilot_generate`:
25
+
26
+ ```bash
27
+ echo '{"maxCandidates":25,"minConfidence":0.8}' | npx --no-install kibi autopilot-generate --input -
28
+ ```
29
+
30
+ ## Capability Workflow
31
+
32
+ - Generate a read-only bootstrap preview with `kb_autopilot_generate`, or the dedicated CLI route `autopilot-generate --input`.
33
+ - Show the generated preview and obtain explicit approval before writes.
34
+ - Apply reviewed entity creation or updates with `kb_upsert`, or `upsert --input`.
35
+ - If cleanup is needed, use `kb_delete`, or `delete --input`, only after checking dependencies and obtaining approval for the specific removal.
36
+ - Finish with `kb_check`, or `check --input`, to validate the branch snapshot.
37
+
38
+ ## Guidance
39
+
40
+ - Keep mutation requests explicit, small, and sequential.
41
+ - Prefer source-linked entities so future `kb_query` lookups can verify repository context against source files.
42
+ - Preserve traceability by linking facts, claims, scenarios, and tests to concrete project files whenever repository evidence supports it.
43
+ - Do not read or edit files inside `.kb` directly; all changes go through the selected Kibi interface.
44
+ - Ask at most four bounded context questions, and only when repository evidence is insufficient.
45
+ - Stop at the documented operator repair boundary if the setup appears partial, inconsistent, or unsupported by the approved interface.
46
+
47
+ ## Public Training Trajectories
48
+
49
+ - `init-kibi-bootstrap-analysis-train-1`: Analyze the cold-start repository and produce a read-only bootstrap preview using only the public Kibi MCP surface.
50
+ - `init-kibi-bootstrap-analysis-train-2`: Analyze the cold-start repository and produce a read-only bootstrap preview using only the public Kibi MCP surface.
51
+ - `init-kibi-bounded-context-questions-train-1`: Ask only the bounded context questions needed before bootstrap synthesis using only the public Kibi MCP surface.
52
+ - `init-kibi-bounded-context-questions-train-2`: Ask only the bounded context questions needed before bootstrap synthesis using only the public Kibi MCP surface.
53
+ - `init-kibi-approval-sequential-writes-train-1`: Apply the approved bootstrap plan sequentially and finish with validation using only the public Kibi MCP surface.
54
+ - `init-kibi-approval-sequential-writes-train-2`: Apply the approved bootstrap plan sequentially and finish with validation using only the public Kibi MCP surface.
55
+ - `init-kibi-repair-escalation-train-1`: Identify the partial setup and stop at the documented operator repair boundary using only the public Kibi MCP surface.
56
+ - `init-kibi-repair-escalation-train-2`: Identify the partial setup and stop at the documented operator repair boundary using only the public Kibi MCP surface.
57
+
58
+ ## Training Data
59
+
60
+ ```json
61
+ [{"taskId":"init-kibi-bootstrap-analysis-train-1","family":"bootstrap-analysis","reflection":"Analyze the cold-start repository and produce a read-only bootstrap preview. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"init-kibi-bootstrap-analysis-train-2","family":"bootstrap-analysis","reflection":"Analyze the cold-start repository and produce a read-only bootstrap preview. This is train case 2; use only the public Kibi MCP surface."},{"taskId":"init-kibi-bounded-context-questions-train-1","family":"bounded-context-questions","reflection":"Ask only the bounded context questions needed before bootstrap synthesis. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"init-kibi-bounded-context-questions-train-2","family":"bounded-context-questions","reflection":"Ask only the bounded context questions needed before bootstrap synthesis. This is train case 2; use only the public Kibi MCP surface."},{"taskId":"init-kibi-approval-sequential-writes-train-1","family":"approval-sequential-writes","reflection":"Apply the approved bootstrap plan sequentially and finish with validation. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"init-kibi-approval-sequential-writes-train-2","family":"approval-sequential-writes","reflection":"Apply the approved bootstrap plan sequentially and finish with validation. This is train case 2; use only the public Kibi MCP surface."},{"taskId":"init-kibi-repair-escalation-train-1","family":"repair-escalation","reflection":"Identify the partial setup and stop at the documented operator repair boundary. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"init-kibi-repair-escalation-train-2","family":"repair-escalation","reflection":"Identify the partial setup and stop at the documented operator repair boundary. This is train case 2; use only the public Kibi MCP surface."}]
62
+ ```
@@ -0,0 +1,44 @@
1
+ ---
2
+ id: kibi-freshness
3
+ name: kibi-freshness
4
+ description: Check branch freshness and source linkage quality before decisions or risky writes.
5
+ version: 1.0.0
6
+ kibiCompatibility: "*"
7
+ tags:
8
+ - kibi
9
+ - mcp
10
+ - freshness
11
+ - agent-guidance
12
+ ---
13
+ ## Goal
14
+
15
+ Help agents decide whether Kibi knowledge is current enough to support safe changes while preserving source-file traceability and approved interface boundaries.
16
+
17
+ ## Interface Selection
18
+
19
+ 1. If Kibi MCP tools are visible and approved for the workspace, use the MCP surface only.
20
+ 2. Otherwise, in a trusted workspace, use the canonical project-local CLI fallback through `npx --no-install kibi ...` or `bunx --no-install kibi ...`.
21
+ 3. If the project-local CLI is unavailable or too old, stop and tell the operator to enable or install Kibi.
22
+ 4. Never use a global fallback or an installing runner.
23
+
24
+ Use `kibi-usage/resources/operation-access.md` for exact dedicated routes. A project-local CLI freshness check is executable as:
25
+
26
+ ```bash
27
+ echo '{}' | npx --no-install kibi status --input -
28
+ ```
29
+
30
+ ## Capability Workflow
31
+
32
+ - Use `kb_status`, or `status --input`, first to confirm branch attachment, freshness state, dirty-worktree evidence, and whether the knowledge snapshot is safe to rely on.
33
+ - Use `kb_query`, or `query --input`, with `sourceFile` and text references for source-linked discovery.
34
+ - Re-run `kb_search`, or `search --input`, after sync gaps or stale context are detected.
35
+ - If knowledge must change, use the selected interface's `kb_upsert`/`upsert` or `kb_delete`/`delete` operation sequentially, then finish with `kb_check`/`check`.
36
+
37
+ ## Guidance
38
+
39
+ - Prefer the public Kibi MCP surface whenever it is available and approved.
40
+ - Never proceed with broad changes when freshness is stale and unresolved.
41
+ - If entities look stale, refresh context through an approved Kibi capability and then re-query.
42
+ - Preserve source-file traceability by carrying `sourceFile`, text references, and validation evidence through discovery, mutation, and completion.
43
+ - Do not read or edit files inside `.kb` directly; use the selected Kibi interface instead.
44
+ - Completion must state one freshness outcome: KB updated, no KB impact with rationale, or deferred/failed.
@@ -0,0 +1,54 @@
1
+ ---
2
+ id: kibi-traceability
3
+ name: kibi-traceability
4
+ description: Maintain requirement, scenario, and test traceability through Kibi MCP tools.
5
+ version: 1.0.0
6
+ kibiCompatibility: "*"
7
+ tags:
8
+ - kibi
9
+ - mcp
10
+ - traceability
11
+ - agent-guidance
12
+ ---
13
+ ## Goal
14
+
15
+ Validate and strengthen requirement, scenario, test, behavioral-symbol, and source-file traceability before and after code changes.
16
+
17
+ ## Interface Selection
18
+
19
+ 1. If Kibi MCP tools are visible and approved, use the MCP surface as the primary authority.
20
+ 2. Otherwise, in a trusted workspace, use the canonical project-local CLI fallback through `npx --no-install kibi ...` or `bunx --no-install kibi ...`.
21
+ 3. If neither approved MCP tools nor the project-local CLI are available, or if the CLI is unavailable or too old, stop and tell the operator to enable or install Kibi.
22
+ 4. Never use a global fallback or an installing runner.
23
+
24
+ Use MCP routes for modeling, querying, checking, validation, and cleanup. Use the project-local CLI only as the fallback interface, passing JSON input through stdin. Example:
25
+
26
+ ```bash
27
+ echo '{"sourceFiles":["src/auth/login.ts"],"includeImpactDiagnostics":true,"includeWorkingTreeDiff":true}' | npx --no-install kibi check --input -
28
+ ```
29
+
30
+ ## Capability Workflow
31
+
32
+ - Locate requirements through `kb_search` or `search --input`, then inspect exact records through `kb_query` or `query --input`.
33
+ - Before meaningful edits, identify linked requirements, scenarios, tests, facts, source files, and behavioral symbols relevant to the planned change.
34
+ - After meaningful source edits, run `kb_check({sourceFiles:[...], includeImpactDiagnostics:true, includeWorkingTreeDiff:true})` or the equivalent `check --input` JSON recipe before deciding whether traceability is current.
35
+ - Apply traceability updates sequentially through `kb_upsert` or `upsert --input` for requirements, scenarios, tests, facts, behavioral symbols, and source-linked relationships.
36
+ - Validate constraints and consistency through `kb_check` or `check --input` after updates.
37
+ - Use `kb_delete` or `delete --input` only for explicit cleanup of obsolete records or relationships.
38
+
39
+ ## Guidance
40
+
41
+ - Prefer source-linked relationships so requirements, scenarios, tests, symbols, and files can be traced cleanly.
42
+ - Preserve source-file traceability whenever adding or changing requirements, scenarios, tests, facts, behavioral symbols, or implementation links.
43
+ - Preserve the canonical chain `REQ-* -> SCEN-* -> TEST-*` when adding or changing requirements.
44
+ - Production symbols should implement requirements; test symbols should remain executable evidence for tests.
45
+ - Resolve impact at behavioral-symbol granularity when Kibi reports symbol-level diagnostics; avoid treating a whole file as impacted when the report identifies narrower linked behavior.
46
+ - Treat `symbol_semantic_review_needed` as a prompt to inspect linked requirements and tests; Kibi reports graph links but does not prove prose semantics.
47
+ - Do not read or edit files inside `.kb` directly; all modeling and cleanup goes through the selected Kibi interface.
48
+ - Keep approval boundaries intact: only use Kibi MCP tools that are visible and approved, and only use the project-local CLI fallback in a trusted workspace.
49
+
50
+ Public training trajectories:
51
+ [{"taskId":"kibi-traceability-requirement-discovery-train-1","family":"requirement-discovery","reflection":"Discover the requirement linked to the supplied source symbol. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-requirement-discovery-train-2","family":"requirement-discovery","reflection":"Discover the requirement linked to the supplied source symbol. This is train case 2; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-symbol-impact-granularity-train-1","family":"symbol-impact-granularity","reflection":"Resolve impact at behavioral symbol granularity rather than file granularity. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-symbol-impact-granularity-train-2","family":"symbol-impact-granularity","reflection":"Resolve impact at behavioral symbol granularity rather than file granularity. This is train case 2; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-relationship-chain-train-1","family":"relationship-chain","reflection":"Trace the requirement, scenario, and test relationship chain. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-relationship-chain-train-2","family":"relationship-chain","reflection":"Trace the requirement, scenario, and test relationship chain. This is train case 2; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-executable-coverage-train-1","family":"executable-coverage","reflection":"Establish executable test identity and behavioral coverage links. This is train case 1; use only the public Kibi MCP surface."},{"taskId":"kibi-traceability-executable-coverage-train-2","family":"executable-coverage","reflection":"Establish executable test identity and behavioral coverage links. This is train case 2; use only the public Kibi MCP surface."}]
52
+
53
+ Previous development gate:
54
+ {"mean":0,"hardPasses":0,"worstFamilyMean":0}