kibi-cursor 2.2.0 → 2.3.0

package/.cursor-plugin/plugin.json

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

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # kibi-cursor
 
+## 2.3.0
+
+### Minor Changes
+
+- f8fff87: The telemetry acceptance and remediation reports now show whether agents look requirements up before they change requirement-linked code. A new `lookup_before_first_edit` metric gives, per host session, the share of sessions that ran `kb_search` or `kb_query` (through MCP or the CLI) before their first edit of a file whose symbols implement a requirement. Sessions that edited first appear in the report with the file and its exact `.kb/usage.log` line. The data comes from opt-in hook rows that every Kibi host plugin now writes when `KIBI_DIAGNOSTIC_MODE` is set; nothing is recorded otherwise.
+
+  - `kibi usage-metrics` / `kb_check` telemetry acceptance: new metric `lookup_before_first_edit` (threshold `>=` policy `lookupBeforeFirstEditMinimum`, default 1) with evidence `unguidedEditPaths` and `lookupOperations`. It is `not_applicable` when no host hook recorded a requirement-linked edit, so logs without hook rows are judged as before. A failed metric adds the advisory diagnostic `lookup_before_first_edit_bypassed` (rank 35).
+  - `kibi usage-remediation`: one event item per session whose first linked edit had no earlier lookup, pointing at that hook row.
+  - `parseTelemetryUsageLog` still returns only Kibi operation rows; hook rows stay attached to the returned array (read them with `partitionTelemetryUsage`). Remediation `logLine` values now count hook rows and blank lines, so they match the file.
+  - `kibi-agent-core/hook-usage-log`: shared `appendHookUsage` / `appendHookUsageRows`, `kbUsageTrace` and `editTraces`. Hook rows (`interface: "hook"`) carry `host`, `session_id`, `hook_action` (`kb_usage` or `edited`), `kb_operation`, `path`, `path_kind` and `requirement_ids`. `hostKbOperation` recognizes MCP tool names and `kibi <route>` shell commands; `extractEditedPaths` reads `apply_patch` headers.
+  - Claude Code: `edited` rows now carry the file's `requirement_ids`, and every row names its `host`. Cursor (`postToolUse`), Codex and ZCode (`PostToolUse`) and OpenCode (`tool.execute.after`) now write the same `kb_usage` and `edited` rows.
+
+- 1012d1c: When an agent edits a file that implements a requirement, every Kibi host plugin (Claude Code, Cursor, Codex, ZCode and OpenCode) now says what that requirement must keep true and the decision behind it, not just its ID. The extra lines come from the requirement's linked facts and ADR, so agents see the constraint before they change the code. All hosts build the snippet with one shared builder in `kibi-agent-core`, so they show the same lines within each host's size limits, and none of them presents a superseded or retired requirement as current.
+
+  - New `kibi-agent-core/snippets` export: `fileKnowledgeSnippet`, `requirementGroundingLines`, `editKnowledgeContext`, `editFocus` and `createEntitySummarizer`. Edit snippets add "`<REQ>` must keep true: …" (up to two facts linked via `constrains`, `requires_property`, `requires_predicate` or `requires_rule`) and "Decision: `<ADR>`" for the lead requirement. Read snippets keep the requirement and test lines only.
+  - A superseded, deprecated or retired lead requirement gets no "must keep true" or "Decision" lines, so retired policy is not shown as current.
+  - Claude Code: the `PreToolUse` edit snippet now comes from the shared builder (no change in content).
+  - Cursor: `preToolUse` edit guidance and `beforeReadFile` / read guidance include the shared snippet for files whose symbols implement a requirement, followed by the existing "query before you change it" follow-up.
+  - Codex: `PreToolUse` on `apply_patch` (and other edit tools) returns the snippet as `additionalContext`, for up to three changed files per call and once per file per session. Paths come from the patch's `*** Update/Add/Delete File:` headers.
+  - ZCode: `PreToolUse` on edit tools returns the snippet as `additionalContext`, including "The edit is inside `<symbol>`" when the edited text is found, once per file per session.
+  - OpenCode: the edit-guidance system prompt adds one "must keep true … Decision …" bullet (one fact) for the focus file, within the existing word budget.
+  - `readEntitySummary` returns frontmatter `links` (plain entries read as `relates_to`; `type` and `target` in either order) merged with the entity's records in `.kb/relationships` shards, so grounding stored only in shards still reaches the snippet.
+  - Session and discovery hints point at `kb_search` questions and its answer layer instead of asking for `rankingMode: "intent-v1"`, which is now the default.
+
+### Patch Changes
+
+- 89870c1: Bootstrap now checks its write actions before review and application, so ordinary require/forbid claims can be applied without malformed facts or semantic-inventory failures. Invalid and ungroundable claims remain cited authoring follow-ups; product intent receives priority over repository observations, and excluded or unreadable candidates are reported. Deterministic failures stop in a terminal journal with committed actions listed and guidance to re-plan; interrupted writes still recover.
+
+  Encode polarity as an `eq` boolean `true` comparison with a require/forbid modifier in the shared strict builder, retaining existing stable IDs. Add writer-schema and semantic-inventory preflight, per-claim extraction diagnostics, task-list normalization, selection accounting, and terminal failure reporting through CLI/MCP status and result envelopes.
+
+  Migration: KB schema 7 makes `strict-fact-shape` a blocking canonical check. Run `kibi migrate --yes`, then `kibi sync`. The migration rewrites legacy polarity-only property facts to the typed boolean encoding while preserving IDs, polarity, relationships, and document bodies. Other malformed strict facts require explicit correction; they are not treated as proof.
+
+- 15356de: Host hooks no longer ask for a `kb_check` after a `kb_upsert` dry run. A dry run only validates, so the Cursor, Codex, ZCode and OpenCode hooks now count it as validation rather than a KB write.
+
+  - `extractKbMcpToolCall` reports `kb_upsert` with `dryRun: true` as `kb_validate_upsert`.
+  - OpenCode's freshness evidence records a dry-run upsert as `kb_validate_upsert`, which carries no mutation evidence.
+
+- 1012d1c: Kibi keeps answering from the right place when you work in a git worktree, a detached checkout, or on a machine without Prolog. Host launchers no longer pin the MCP server to the first workspace, so per-call workspace routing keeps working, and a missing Prolog runtime points at `kibi doctor` instead of failing opaquely.
+
+  - Claude Code, Codex, Cursor and Z Code launchers set `KIBI_MCP_ATTACH_ROOT` instead of `KIBI_WORKSPACE`; the server starts in that directory without disabling routing. `KIBI_WORKSPACE`, `KIBI_PROJECT_ROOT` and `KIBI_ROOT` still pin.
+  - A detached HEAD whose commit is the tip of exactly one local branch attaches that branch's KB.
+  - `kb_status` reports `swipl_*` error codes with a `kibi doctor` remediation when the Prolog runtime cannot be resolved.
+  - CI and publish check that the committed Claude hook bundle matches its source.
+
+- Updated dependencies [15356de]
+- Updated dependencies [f8fff87]
+- Updated dependencies [1012d1c]
+  - kibi-agent-core@0.2.0
+
 ## 2.2.0
 
 ### Minor Changes
@@ -12,6 +61,7 @@
 ### Patch Changes
 
 - 676bac9: The Claude Code, Codex, Cursor, and ZCode plugins now tell the Kibi MCP server which workspace each call is about, so sessions working in a git worktree are answered from that worktree's branch instead of the checkout the server started in. Nothing changes for sessions that stay in one project.
+
   - Each plugin's pre-tool hook adds `workspaceRoot`, the agent's current Kibi workspace, to every Kibi MCP call. Claude Code, Cursor, and ZCode send it without a permission decision so the host's own approval flow is unchanged; Codex requires `permissionDecision: "allow"` for input rewrites, which does not override a server's tool approval mode.
   - `kibi-agent-core` exports `KIBI_WORKSPACE_ARGUMENT`, `isKibiMcpToolName`, and `stampKibiWorkspace` for the plugins.
   - The Codex hook parser now reads `hook_event_name`, the field Codex actually sends; the Claude and ZCode `PreToolUse` matchers include `mcp__.*__kb_.*`.
@@ -25,6 +75,7 @@
 ### Patch Changes
 
 - 7aa1471: Kibi can now run without a hand-installed SWI-Prolog. It looks for an explicit `KIBI_SWIPL` executable first, then the tested SWI-Prolog build shipped in the new `kibi-swipl` platform packages, and only then `swipl` on `PATH` (9.0 or newer). `KIBI_SWIPL=system` skips the bundle. `kibi doctor` now reports which runtime was chosen (source, path, version), checks that every required library loads, and explains which platform package to add when the bundle is missing. A running Kibi engine that was started with a different SWI-Prolog is restarted instead of reused. Release builds now ship the tested SWI-Prolog for Linux x64, Linux arm64, macOS arm64, and macOS x64 inside the `kibi-swipl-<platform>` packages, and an install that skips optional dependencies still succeeds and explains which package to add.
+
   - kibi-cli: add `resolveSwipl()` (env, bundled with manifest and SHA-256 verification, PATH), a per-process cache, and `SWI_HOME_DIR` for bundled builds in both `PrologProcess` spawn paths.
   - kibi-cli: engine handshake and requests carry the resolved `<bin>@<version>`; the daemon rejects mismatches and clients replace a mismatched daemon.
   - kibi-cli: `doctor` SWI-Prolog check uses the resolver and loads all required libraries.
@@ -34,6 +85,7 @@
   - New packages `kibi-swipl` and `kibi-swipl-<platform>` start at 1.0.0 outside this changeset and version together through a changesets fixed group.
 
 - db5376c: Projects can now opt into impact reviews that bind a change to its exact source, knowledge decisions and trusted analysis policy. Kibi validates both staged changes and a complete pull-request diff, rejects stale review evidence, and lets agents prepare an unauthored review template through the CLI or MCP instead of hand-assembling one. Every decision and reviewer field stays for an agent to write; preparation never approves or proves anything.
+
   - Add versioned impact policy and review schemas, immutable review fingerprints, reviewed Python decorator coordinate migration and the trusted aggregate `check-diff` command.
   - Add the read-only `prepare-impact-review --input` CLI route and `kb_prepare_impact_review` MCP operation; regenerate the bundled operation-access catalog for the agent integrations.
   - Keep the sample CI workflow inactive until it is adopted on a protected target.
@@ -59,22 +111,26 @@
   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.
@@ -86,6 +142,7 @@
   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.
@@ -103,11 +160,13 @@
 ### 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`.
@@ -123,6 +182,7 @@
 ### Major Changes
 
 - 812c201: Kibi's proof layer is now runner-neutral: any test runner, script, or harness can prove requirements, and Playwright is no longer built into the proof model.
+
   - `kibi prove` replaces `kibi verify` as the single command to run configured proof producers and record evidence. Proof contracts (`kibi.proof-contract.v1`) declare explicit obligations (`symbol_id` + `target`) executed by a configured integration in `.kb/proof/integrations.json`; `kibi proof inspect` discovers test infrastructure deterministically; one producer run can satisfy many test contracts, and re-ingestion is idempotent.
   - Evidence moves to the `kibi.proof-run.v1` artifact (typed environment, run-level outcome, factual attempt history with `native_case`/`aggregate_run` provenance) evaluated into `kibi.proof-receipt.v1` receipts bound to the live snapshot, contract hash, and effective execution fingerprint. Command proof is the universal fallback, so every project can prove requirements without a first-party framework adapter; strict first-attempt policy never upgrades unknown attempt history into passing evidence.
   - Breaking removals: `kibi verify`, `kb_ingest_verification`, `kibi.playwright-run.v1`, `verification_contract`/`verification_receipts` entity fields (replaced by `proof_contract`/`proof_bindings`/`proof_receipts`), the `required_case_symbols`×`required_projects` Cartesian contract, and `retries` fields. Migrate by re-running `kibi prove` after bootstrap configures proof for your repository.
@@ -132,10 +192,12 @@
 ### Patch Changes
 
 - b0271ac: Cursor now starts the bundled Kibi MCP server reliably when it launches plugin processes from a home directory or another unrelated working directory. Consumer workspaces with spaces continue to resolve their project-local `kibi-mcp` installation, while the portable Agent Plugin keeps its separate `npx --no-install` configuration.
+
   - Fix `kibi-cursor` MCP launcher arguments to use Cursor's `${CURSOR_PLUGIN_ROOT}` expansion.
   - Add source-install manifest regression coverage for consumer-local resolution from unrelated host directories.
 
 - b1682f1: Agents receive clearer guidance for repairing the actual supplied mutation request and preserving approved predicate bindings. The scoped additions retain the existing workflow while separating payload recovery from conditional relational modeling.
+
   - Update `kibi-usage` to 2.1.2 in CLI/runtime sources and the generated Codex/Cursor distributions.
   - Preserve the other three skills and all existing resource content.
   - Retain production-adoption safeguards; development comparisons are not held-out evidence.
@@ -144,10 +206,12 @@
   same entry paths tests already spawn as processes. In-process coverage can
   exercise stdin, CLI guards, and realpath failures instead of leaving those
   lines invisible to Codecov.
+
   - Export hook CLI helpers and Agent Plugin / launcher internals for tests.
   - Use a namespace `fs` import in skill validation so realpath errors are testable.
 
 - 5999143: Agent-facing skill docs now use the current status field names, so agents following the freshness and E2E receipt workflows look for fields that actually exist in `kb_status` output instead of stale ones.
+
   - Bundled `kibi-freshness` and `kibi-usage` skills (all agent mirrors) now reference `proofSnapshotChanges` and `proofSnapshot` (previously `verificationSnapshotChanges`/`verificationSnapshot` from the pre-proof-architecture status schema).
   - The skillopt-eval harness reads `proofSnapshot*` status fields and its held-out eval prompts name the current fields, so "dirty editor path" evidence gathering works against live status output again.
 
@@ -169,6 +233,7 @@
 - 9e6fb3f: Kibi now uses one opinionated project contract: all Kibi-managed knowledge lives under `.kb/`, check enforcement is owned by the installed Kibi version, and projects can no longer weaken health by disabling rules or relocating entity paths in `.kb/config.json`. Existing repositories must run `kibi migrate --yes` to move legacy `documentation/...` knowledge into the canonical layout and adopt `.kb/manifest.json`.
 
   Advisory modeling checks still run by default, but they report as non-blocking quality diagnostics instead of failing `kibi check`. Migration rewrites the old blanket `.kb/` gitignore stanza so authored lanes are trackable, and a malformed leftover `config.json` blocks the one-way cutover instead of guessing default paths.
+
   - Remove user-configurable entity paths and persistent `checks.rules` overrides; retire `.kb/config.json` after migration.
   - Introduce `.kb/manifest.json` for Kibi-owned lifecycle metadata (schema version, semantic backfill state).
   - Add one-way legacy storage migration (`documentation/` and custom configured paths → `.kb/<lane>/`).
@@ -193,6 +258,7 @@
   effect and repair information, while branch stores are hashed and explicitly
   identity-bound. The mutation path can author tracked source documents and
   canonical relationship shards without staging or committing them.
+
   - Add the `kibi-runtime` first-party integration package.
   - Add exact branch-store manifests, explicit legacy migration/quarantine, and
     typed result/effect contracts.
@@ -200,20 +266,24 @@
     approval plans.
 
 - 3d7d04f: Generic MCP and CLI agents now discover Kibi's operating rules from bundled skills instead of a long copy-paste prompt. Improving an existing product KB is covered by a `kibi-usage` resource rather than a second manual, so agent guidance stays in one place and cannot drift from the packaged workflow.
+
   - Add `kibi-usage` `resources/kb-improvement.md` and bump that skill to 2.1.0.
   - Replace `docs/prompts/llm-rules.md` with `docs/generic-agent-onboarding.md`.
   - Remove the obsolete retroactive-init prompt; bootstrap stays in the `kibi-bootstrap` skill.
 
 - 29793c7: The Cursor stop hook no longer starts an extra Kibi follow-up after you only deliver a plan. Reads and search no longer look like source edits, so plan mode can finish without an impact-check nudge. If that same turn actually edited source or updated the knowledge base, the existing follow-up still runs.
+
   - Record dirty paths only from known editable tools.
   - Treat `CreatePlan` as plan delivery and stay silent at stop unless that turn also edited source or mutated the KB.
   - Skip follow-up when `stop.status` is `aborted` or `error`.
 
 - 8db2e37: Cursor plugin users can now enable Kibi without adding a separate project MCP configuration. The plugin finds the `kibi-mcp` version installed in the opened project, starts it inside that workspace, and reports a clear setup error when the dependency is missing. It never downloads or falls back to a global Kibi runtime.
+
   - Replace the plugin MCP `npx --no-install` command with the packaged consumer-workspace launcher.
   - Cover isolated and packed plugin launches, workspace selection, package-layout resolution, exit codes, and signal forwarding.
 
 - 535dea8: Agents can now keep working in synthetic, detached, or unreadable workspaces while Kibi reports the migration work it can evaluate. Coverage and checks preserve their useful domain results when branch status is unavailable, and the Codex/Cursor skill assets now stay aligned with their published plugin metadata.
+
   - Keep status-derived migration actions read-only and append them only when branch resolution succeeds.
   - Preserve the shared migration-plan contract across coverage and checks without requiring a Prolog-backed status query in non-Git harnesses.
   - Synchronize plugin manifests and freshness skill CLI examples for the next coordinated patch release.
@@ -223,6 +293,7 @@
   edges can no longer hide a newer contradictory policy merely by making that
   newer requirement non-current. Relationship checks also block authored links
   that have silently disappeared from compiled knowledge.
+
   - Document `supersedes` as new-to-old across bundled and generated skills.
   - Reject reversed supersession when tracked source history proves that the
     purported replacement predates its target.
@@ -290,11 +361,13 @@
 ### Patch Changes
 
 - de7b85a: Verification contracts can now evolve without forcing projects to erase valid historical test evidence. Kibi preserves every earlier receipt, accepts a newly appended receipt for the current contract, and only treats evidence matching both the current contract and live code snapshot as proof.
+
   - Separate immutable receipt-history validation from current-contract binding during verification ingest.
   - Report `verification_contract_mismatch` as an explicit proof gap until current-contract evidence is appended.
   - Teach the usage skill and SkillOpt evaluator to preserve older-contract receipts and forbid history rewrites.
 
 - 584336b: Agents now get consistent guidance when execution proof, structural coverage, and KB freshness disagree. Current-contract E2E evidence is recorded as v2 without rewriting history, and full checks no longer report a contradictory weak-depth warning when the same live receipt already proves the scenario-backed test. Receipt freshness repairs also identify the affected requirements and tests so agents can rerun the exact contract.
+
   - Share snapshot-bound proof evidence with full quality diagnostics.
   - Add bounded receipt-gap telemetry and v2-native remediation guidance.
   - Document and test the new receipt and proof-aware diagnostic requirements.
@@ -302,6 +375,7 @@
   - Keep the MCP package contract verifier self-contained with an explicit semver development dependency and matching workspace lock ranges.
 
 - Kibi can now explain a missing or damaged branch-local KB without changing it. Agents receive a precise recovery path, preserving the existing store before a deliberate rebuild, and no longer need to guess whether a clean check also means a clean, fresh KB.
+
   - Add non-mutating branch-store inspection to status and a preview-first `kibi branch recover --apply` workflow.
   - Restrict branch migration to the detected historical `master` -> legacy `main` compatibility attachment; arbitrary branch moves are refused.
   - Refresh CLI/MCP status documentation, mirrored agent skills, and release-gate packed consumer coverage.
@@ -337,6 +411,7 @@
   Diagnostic workflows now produce correlated evidence through both CLI JSON and MCP surfaces. Operators can run a read-only versioned remediation report that points to exact unmatched log events, preserves explicit missing-coverage work, and prevents advisor or preflight evidence from a different identified session or actor from counting as proof.
 
   Legacy prose can now be inspected one requirement at a time through a deterministic migration preview. The preview preserves existing code evidence, binds every extracted proposition to exact authored source, ranks project-local ontology candidates, and never emits an auto-applicable write.
+
   - Add the shared `kibi.requirement-proof.v2` Prolog evaluator and expose its rows, fresh receipt evidence, and summary counts through CLI and MCP coverage.
   - Persist generated symbol coordinates and symbol metadata into normal and staged RDF projections.
   - Preserve semantic-inventory JSON through mutation, sync, RDF storage, and query round trips, and refresh coordinates before extracting their manifest overlay.
@@ -358,22 +433,26 @@
 ### Patch Changes
 
 - 5e4e126: Agents no longer treat Kibi's CLI as an MCP fallback. MCP tools and the trusted project-local CLI are presented as peer surfaces over the same 18 operations, and agent guidance now selects whichever interface is visible and approved in the current environment. The CLI's `--input` JSON routes remain first-class for agent automation, with no preference order implied.
+
   - Reframe `kibi-usage` Interface Selection and the operation-access preference column to peer surfaces.
   - Update OpenCode prompt injection, enforcement, and init-kibi guidance.
   - Update the MCP init-kibi prompt and the staged-impact evidence resolution text.
   - Re-sync the Cursor and Codex skill bundles.
 
 - Codex and Cursor users now receive the same verified prose-to-logic guidance as the Kibi CLI. The bundled `kibi-usage` skill explains proposition coverage, typed Logic IR safety, predicate recovery, and contradiction-aware validation without relying on repository-specific release conventions.
+
   - Synchronize the Logic IR, fact-lane, workflow, and portable skill guidance into both agent bundles.
   - Keep the bundled skill manifests and canonical hashes aligned with the CLI public skill.
 
 - 5e4e126: Kibi now ships as a portable Agent Plugin alongside the existing Cursor Plugin. The open Agent Plugins standard (agent-plugins.org) packages Kibi's Agent Skills and MCP server so any compatible client — Cursor, Copilot, OpenCode, and others — loads Kibi's capabilities without client-specific adaptation. The Cursor Plugin keeps Cursor-only components (rules, commands, hooks), and both formats are listed in the same marketplace.
+
   - Add a committed portable Agent Plugin artifact at `agent-plugin/` with a conformant `plugin.json` manifest (plugin.schema.json 1.0.0).
   - Generate the artifact's `mcp.json` with the required `$schema` and `stdio` server type.
   - List the Agent Plugin (`plugins/kibi-agent-plugin`) in the repo marketplace alongside `kibi-cursor`.
   - Add `scripts/build-agent-plugin.ts` to regenerate the artifact and keep its skills in sync with the canonical bundle.
 
 - 2a85fc8: Kibi can now track whether every atomic clause in a normative requirement has a queryable logical representation. Readable prose remains intact, while stable claim keys, linked strict-property or predicate facts, and a requirement manifest expose incomplete modeling before it silently weakens contradiction detection. Exact opposite polarities over the same ground predicate now produce a contradiction.
+
   - Remove repository-specific release and optimizer-corpus text from `kibi-usage`.
   - Add portable clause-complete prose-to-ground-predicate/property guidance and examples.
   - Preserve logical claim and predicate-schema fields through Markdown sync.
@@ -391,6 +470,7 @@
 - 2f9073c: Kibi now ships optional guidance for recording UI and visual expectations, so agents working on a screen can discover "where things live" and cannot silently drift the layout. A prose requirement anchors the full visual description, checkable positions, alignment, and header ordering decompose into strict facts that reject conflicting writes, and relational alignment uses the built-in `visual_layout_rule` predicate. The lane is per-project: non-UI projects simply never model UI subjects, and no validation rule requires them.
 
   Also, `kb_status` within a long-lived MCP session now observes same-session file and KB changes instead of returning a stale cached result. Compound Prolog goals (such as the status query) are no longer cached in one-shot mode, so a status check after a source or documentation edit reports the current freshness state.
+
   - Add `docs/ui-requirements.md` with the three-layer UI modeling guide, payload-shaped examples, and the check workflow.
   - Point the modeling cheatsheet decision tree, agent LLM rules, and the AGENTS quick references at the new UI lane.
   - Add a self-contained `kibi-usage` skill resource (`resources/ui-requirements.md`), declare it in the skill manifest, and add a UI modeling workflow section.
@@ -422,10 +502,12 @@
 ### Patch Changes
 
 - cafa25f: Agents can now select Kibi by available capability instead of stopping at MCP-specific guidance. The bundled skills prefer approved MCP tools, fall back safely to a project-local non-installing CLI runner, and provide executable JSON recipes plus an exact 18-operation access catalog.
+
   - Document every shared MCP operation's dedicated CLI route, input mode, effects, Prolog requirement, mutability, and telemetry handling.
   - Regenerate Cursor and Codex skill mirrors from the canonical capability-based source.
 
 - 23e815a: Agents can now keep using Kibi when MCP tools are unavailable but a trusted project-local CLI is ready. Guidance across Cursor, OpenCode, and MCP documentation now selects the interface by capability and stops for operator action only when neither safe surface is available.
+
   - Replace MCP-exclusive guidance with the visible-MCP, trusted-CLI JSON route, and blocked state machine.
   - Preserve direct `.kb/` access prohibitions, discovery-before-mutation, sequential writes, and completion validation gates.
 
@@ -441,6 +523,7 @@
 - f1db710: Kibi check outputs now have a stable advisory diagnostics lane for auditability review signals. Operators and MCP clients can receive `qualityDiagnostics` alongside hard `violations` without advisory-only findings changing pass/fail counts or exit behavior. Existing staged impact failures, including symbol granularity violations, remain blocking. Source impact analysis now also highlights overly broad symbols, indistinguishable symbol coordinates, and mixed-purpose component/class ownership as review-only guidance.
 
   Technical summary:
+
   - Add the public `QualityDiagnostic` type with `error`, `warning`, `review`, and `info` severities plus explicit `blocking` semantics.
   - Preserve existing `violations`, `diagnostics`, and `impactDiagnostics` fields while adding MCP structured `qualityDiagnostics` output support.
   - Preserve explicitly filtered MCP `kb_check` rule semantics so advisory full-KB quality scans only run for unfiltered checks or requested impact diagnostics.
@@ -455,6 +538,7 @@
 - Kibi now gives agents source-impact feedback while they are still editing, instead of waiting for the commit hook to be the first signal. Meaningful source edits can be checked through MCP with changed-file impact diagnostics, so agents see coarse symbol ownership, stale symbol evidence, and semantic-review prompts while the source context is fresh. OpenCode, Cursor, and Codex adapters now steer agents toward that MCP-first workflow and keep CLI/hooks as the later safety net.
 
   Technical summary:
+
   - Add reusable CLI changed-file impact diagnostics and export them for MCP consumption.
   - Extend MCP `kb_check` with source-file impact options and structured impact output.
   - Update OpenCode, Cursor, and Codex guidance/hooks to request impact-enabled `kb_check` after source edits.
@@ -467,6 +551,7 @@
 - Kibi now gives agents clearer guidance for the diagnostics flow, so the release notes should reflect that the bundled usage text and MCP logging story were tightened together.
 
   This update also keeps the package mirrors aligned where applicable, which helps downstream plugin consumers stay in sync with the canonical guidance.
+
   - Hardened bundled skill guidance for kibi usage.
   - Improved MCP diagnostic logging shape and validation hints.
   - Synced packaged skill copies where they are shipped with the release.
@@ -476,6 +561,7 @@
 ### Patch Changes
 
 - 5d2975a: Cursor stop hooks no longer inject a long multi-line Kibi freshness reminder after every agent response. Follow-ups are now one line, and most sessions stay silent.
+
   - Track `kb_upsert`, `kb_delete`, and `kb_check` MCP usage during the session.
   - Emit no stop follow-up when nothing KB-relevant changed, or when `kb_check` already ran after edits.
   - Emit a short summary (`Kibi KB updated (kb_upsert).`) after KB mutations, or a single-line sync nudge when source files changed without KB activity.

package/README.md

@@ -122,8 +122,9 @@ agent-plugin/
 Hooks are warning-only and never replace MCP/CLI behavior:
 
 - **sessionStart**: bootstrap reminder when `.kb/manifest.json` is missing.
-- **preToolUse**: warns on explicit direct `.kb/**` edits without blocking.
-- **beforeReadFile** and **postToolUse (Read)**: inject source-linked lookup guidance once per path per session.
+- **preToolUse**: warns on explicit direct `.kb/**` edits without blocking. Before the first edit of a file whose symbols implement a requirement, it adds the shared Kibi snippet (from `kibi-agent-core/snippets`, the same builder the Claude Code plugin uses): the requirements and their implementing symbols, what the lead requirement must keep true and the decision behind it, the covering tests, and the symbol the edit lands in. A superseded or retired lead requirement gets no "must keep true" or "Decision" line. Once per path per session.
+- **beforeReadFile** and **postToolUse (Read)**: inject source-linked lookup guidance once per path per session, with the same snippet minus the "must keep true" and "Decision" lines.
+- **postToolUse** (opt-in telemetry): with `KIBI_DIAGNOSTIC_MODE=1`, appends `interface: "hook"` rows with `host: "cursor"` to `.kb/usage.log` for `kb_*` lookups (MCP or `kibi <route>` in Shell) and for edited files with the requirements they implement, keyed by `conversation_id`. `kibi usage-metrics` reads them for the `lookup_before_first_edit` metric. Nothing is written without the variable.
 - **postToolUse (Write/Edit)**: inject traceability and freshness guidance once per path per session, including `kb_check({sourceFiles:[...], includeImpactDiagnostics:true, includeWorkingTreeDiff:true})` for meaningful source edits.
 - **stop**: emits a single freshness or impact-check follow-up when meaningful paths were **edited** during the turn (reads and search do not count). Plan delivery (`CreatePlan`) stays silent unless that same turn also edited source or mutated the KB.
 

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.2.0",
+  "version": "2.3.0",
   "description": "Repo-local, per-branch, queryable knowledge base. Portable Agent Plugin packaging Kibi's Agent Skills and MCP server.",
   "author": { "name": "Kibi" },
   "homepage": "https://github.com/Looted/kibi/blob/develop/docs/install.md",

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

@@ -2,7 +2,7 @@
 id: kibi-bootstrap
 name: kibi-bootstrap
 description: Bootstrap Kibi from the current Git checkout and the project's existing knowledge sources, with a source interview, cited intent claims, preview approval, source-first writes, and repair-safe completion.
-version: 3.1.0
+version: 3.1.1
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -87,6 +87,11 @@ Finish with `kb_check` and `kb_status`.
 Consume the versioned `kibiProtocol: 1` result envelope: inspect `status`, `effects`,
 `diagnostics`, and `nextActions`. On `committed_with_repairs`, execute required
 repair actions and never retry the original mutation.
+On `BOOTSTRAP_PLAN_INVALID`, obtain a corrected preview and approval before
+applying. On `BOOTSTRAP_PLAN_REJECTED`, inspect committed `data.actionResults`
+and re-plan from the current state; the journal is terminal and cannot recover.
+Review `suppressedCandidates`, `sourceOnlySignals`, and diagnostics for invalid,
+ungroundable, unreadable, or over-limit candidates before approving a plan.
 
 Kibi may author tracked Markdown/YAML/manifests and relationship shards
 transactionally, but never Git-stages or commits them. Never read or edit

package/agent-plugin/skills/kibi-bootstrap/resources/bootstrap.md

@@ -14,3 +14,9 @@ approved hash; inspect its typed result
 and follow `nextActions` if it returns `committed_with_repairs`. Direct
 `kb_upsert` is forbidden for every bootstrap task; never manually replay the
 plan through it.
+
+`BOOTSTRAP_PLAN_INVALID` fails before bootstrap writes or a new journal; request
+a corrected plan. `BOOTSTRAP_PLAN_REJECTED` reports a deterministic failure and
+may include earlier committed `data.actionResults`. Re-plan from the current
+state; its terminal journal cannot recover. Review candidate suppressions and
+cited authoring follow-ups, including any `over_limit` entries, before approval.

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.2.0
+version: 2.3.1
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -47,6 +47,18 @@ Use whichever capability is visible and approved. The surfaces are equal peers:
 Hosts may expose prefixed identifiers such as `kibi_kb_search`,
 `kibi_kb_query`, and `kibi_kb_upsert`; map them to the canonical MCP names.
 
+The MCP server keeps its tool list short. Load skills with `kb_skills`
+(`action: "list" | "load" | "read"`; CLI `kibi skill` or `kibi skills
+list|load|read`). Model prose with `kb_model` (`mode: "analyze"` for the
+semantic advisor, `"requirement"` for strict claims, `"predicates"` for
+ontology predicates; CLI `kibi model` or `semantic-advisor`,
+`model-requirement`, `suggest-predicates`). Preflight a write with
+`kb_upsert` plus `dryRun: true` (CLI `upsert` with `"dryRun": true` or
+`validate-upsert`); it validates and writes nothing. Result payloads still name
+catalog operations such as `kb_model_requirement` or `kb_validate_upsert` in
+`recommended_tools` and repair steps; translate them with the list in
+`resources/operation-access.md`.
+
 The CLI JSON route accepts the same business object as MCP:
 
 ```bash
@@ -73,13 +85,19 @@ runs where you are and needs no `workspaceRoot`.
 ## Safe workflow
 
 1. Always discover before you mutate: start with `kb_search`, then exact-filter with `kb_query`. Use
-   `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.
+   `kb_status` when branch or freshness confidence matters. `kb_search`
+   defaults to intent ranking, so you can ask it a question ("what governs
+   checkout rounding?"); its `data.answer` layer lists the current governing
+   requirements with linked facts, scenarios, tests, and ADRs, separates
+   superseded requirements, and labels observations as notes. Each governing
+   requirement also carries a `verdict` (`contradiction`, `infeasible`,
+   `unknown`, or `none`, which is not proof), the `exceptions` that exempt it,
+   and the `unknowns` the checks could not decide. Those links and verdicts are
+   discovery, not proof. Pass `sourceLocations` before changing a source file,
+   and `rankingMode: "legacy"` for literal identifier lookups. See
+   `resources/workflows.md` for the mode recipe.
+2. Resolve genuine ambiguity with the human; use `kb_model` for deterministic
+   interpretation and typed facts.
 3. Create endpoints before relationships and upsert small batches sequentially.
    Keep the canonical `REQ-* -> SCEN-* -> TEST-*` chain.
 4. Author tracked Markdown/YAML/manifests and relationship shards through Kibi;
@@ -91,9 +109,9 @@ runs where you are and needs no `workspaceRoot`.
 Run `kb_check` with specific rules during iteration and the unfiltered final
 check. Never fire `kb_upsert` calls in parallel; create or confirm endpoint
 entities before linking them. The canonical MCP names are `kb_search`,
-`kb_query`, `kb_upsert`, and `kb_check`.
+`kb_query`, `kb_model`, `kb_upsert`, and `kb_check`.
 
-For a task that explicitly supplies a malformed concrete mutation payload, locate and read that public request artifact before choosing an entity, preserving its exact entity ID, type, requested changes, and every intended relationship and endpoint. Do not substitute a seeded or convenient entity for the requested target. Start with kb_search, then exact-filter those targets with kb_query, and run kb_validate_upsert on that same payload; validation is not completion. Correct only diagnosed pre-commit errors and revalidate the corrected payload. Once authorized, apply the identical corrected and authorized payload with kb_upsert. If it returns committed_with_repairs, treat the mutation as committed, follow only the required repair actions, and neither retry it nor trigger unrelated semantic backfill for a schema-only repair. Exact-read every changed entity and relationship endpoint with kb_query, then finish with an unfiltered kb_check followed by a final kb_status.
+For a task that explicitly supplies a malformed concrete mutation payload, locate and read that public request artifact before choosing an entity, preserving its exact entity ID, type, requested changes, and every intended relationship and endpoint. Do not substitute a seeded or convenient entity for the requested target. Start with kb_search, then exact-filter those targets with kb_query, and run kb_upsert with dryRun: true on that same payload (CLI: validate-upsert); validation is not completion. Correct only diagnosed pre-commit errors and revalidate the corrected payload. Once authorized, apply the identical corrected and authorized payload with kb_upsert. If it returns committed_with_repairs, treat the mutation as committed, follow only the required repair actions, and neither retry it nor trigger unrelated semantic backfill for a schema-only repair. Exact-read every changed entity and relationship endpoint with kb_query, then finish with an unfiltered kb_check followed by a final kb_status.
 
 ## Closeout fields
 
@@ -124,8 +142,13 @@ migration, worktrees, quarantine, restore, and purge.
 ## Typed results and recovery
 
 Every CLI JSON/MCP result has `kibiProtocol`, `operation`, `resultVersion`,
-`status`, `data`, `effects`, `diagnostics`, and typed `nextActions`. Treat
-`status: error` as a failed pre-commit operation. If the status is
+`status`, `data`, `effects`, `diagnostics`, and typed `nextActions`.
+`status: error` normally means a failed pre-commit operation. The bootstrap
+error `BOOTSTRAP_PLAN_REJECTED` can follow earlier committed actions: inspect
+`data.actionResults` and `data.applied`, then re-plan from the current state.
+Its journal is terminal; never recover or replay it. `BOOTSTRAP_PLAN_INVALID`
+fails preflight before bootstrap writes or a new journal; obtain a corrected
+plan. If the status is
 `committed_with_repairs`, the mutation already committed: inspect failed effects,
 execute each required repair action in order, and never retry the original
 operation. Record effect failures, followed actions, and unsafe retries in
@@ -138,8 +161,35 @@ Existing entities preserve body bytes when `document.body` is omitted; new
 requirements default their body to `semantic_text`. Relationship mutations
 patch canonical shards while preserving unrelated records. Authored entity
 deletion returns a hash-bound approval plan; requirements normally evolve via a
-new entity linked with `supersedes`. Read `resources/source-authoring.md` before
-source writes, deletion approval, or recovery.
+new entity linked with `supersedes`; set the replaced requirement to
+`status: closed` in the same change, because `kb_check` blocks an open
+superseded requirement and supersession cycles. Kibi compiles `source` from
+the entity's own file and never writes an authored `source` field, so
+`kb_upsert` cannot change one. When `kb_check` blocks a leftover value
+(`source-path-dangling`), run `kibi migrate`: its automatic
+`source_path_rewrite` action removes the value, or rewrites it when the file
+moved. Never hand-edit `.kb/` for it. Read `resources/source-authoring.md`
+before source writes, deletion approval, or recovery.
+
+`kb_apply_plan` applies a whole plan atomically: a failure changes nothing.
+An interrupted plan is settled by the next `kb_apply_plan`, `kb_upsert`, or
+`kb_delete` call, or by `kb_apply_plan` with its `recoveryJournalId`; never
+re-apply the original plan. On a detached HEAD, reads answer from a read-only
+snapshot and writes are refused; check out a branch before mutating.
+
+## Origin and approvals
+
+Entities record `origin` (`kind`: `human`, `agent`, `migration`, or `import`,
+plus optional `ref` and `approved_by`). `kb_upsert` records `kind: agent` on
+entities you create; leave `origin.approved_by` to the person who reviews them.
+An exception (a requirement that `exempts` another) exempts nothing until a
+human sets `approved_by`; `kb_check` flags approvals an agent recorded without
+corroboration. Never fill in an approval yourself. Record why a requirement
+exists in `rationale`, or link the ADR that explains it.
+
+Conditional clauses ("only when", "only if", "must not ... unless") compile
+into typed `forbid` rules linked by `requires_rule`, not property facts; one
+`kb_model` or `kb_compile_intent` cannot translate stays an `ontology_gap`.
 
 ## Semantic and proof guardrails
 
@@ -157,20 +207,20 @@ to committed `proof/baseline.json` with `kibi proof impact`.
 
 ## Predicate Ontology Decision Tree
 
-Call `kb_semantic_advisor` on the complete prose before encoding a clause.
+Call `kb_model` with `mode: "analyze"` on the complete prose before encoding a clause.
 Set requirement `logic_claims` to exactly the assertive `claim_key` values.
-For each relational clause, call `kb_suggest_predicates` with that clause and
+For each relational clause, call `kb_model` with `mode: "predicates"`, that clause, and
 `existingLogicClaims`. If lexical rank is a false positive, retry with the
 reviewed `schemaId`. If `binding_status` is `incomplete`, supply
 `argumentBindings` and retry. Persist `fact_kind: predicate` with the same
 `claim_key` / `claim_text`, then link `REQ -> fact` with `requires_predicate`.
-Use `kb_model_requirement` for strict scalar clauses. Use
+Use `kb_model` with `mode: "requirement"` for strict scalar clauses. Use
 `fact_kind: observation` only for a true ontology gap. The manifest is not
 grounding: run `logic-coverage` so each key binds to one ground fact.
 Relationship direction is fixed, and every `from` in a relationship batch
 must equal the upserted entity ID.
 
-For conditional relational claims, after the initial `kb_suggest_predicates` and before any `kb_upsert`—including one needed for a missing schema—call read-only `kb_model_requirement` to preview suitable scalar or typed-rule modeling. Treat the preview as advisory: do not apply an irrelevant result or create unrequested facts, and retain an approved ground-predicate plan when it captures the whole claim. Preserve supplied arity, ordered argument roles, polarity, bound values, and one claim key per actual assertion; never split arguments across clauses or schemas or alter values to force uniqueness.
+For conditional relational claims, after the initial `kb_model` predicates call and before any `kb_upsert`—including one needed for a missing schema—call read-only `kb_model` with `mode: "requirement"` to preview suitable scalar or typed-rule modeling. Treat the preview as advisory: do not apply an irrelevant result or create unrequested facts, and retain an approved ground-predicate plan when it captures the whole claim. Preserve supplied arity, ordered argument roles, polarity, bound values, and one claim key per actual assertion; never split arguments across clauses or schemas or alter values to force uniqueness.
 
 ## Symbol-First Traceability
 

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

@@ -4,7 +4,7 @@ Requirement prose remains the human-readable source. Facts add queryable semanti
 
 ## Atomic Claim Coverage
 
-Logical coverage is clause-based, not entity-based. Give `kb_semantic_advisor` the complete requirement body and verify that its `clauses` list contains every atomic obligation. Supply the `clauses` input yourself when automatic splitting would combine or omit obligations. For every normative clause:
+Logical coverage is clause-based, not entity-based. Give `kb_model` (`mode: "analyze"`) the complete requirement body and verify that its `clauses` list contains every atomic obligation. Supply the `clauses` input yourself when automatic splitting would combine or omit obligations. For every normative clause:
 
 - preserve the returned stable key as `claim_key` and the exact clause as `claim_text` on its ground fact;
 - add the key to the exact current `logic_claims` set, removing only stale keys whose propositions no longer exist in the source;
@@ -17,7 +17,7 @@ Example compound prose: “Checkout requires payment authorization before order
 
 ## Predicate Lane (Relational Claims)
 
-Call `kb_semantic_advisor`, then `kb_suggest_predicates`. Apply a candidate only when its schema meaning and ordered arguments fit the claim. Use the returned `applyPlan` rather than hand-writing unsupported predicate names, and link the requirement to the predicate fact with `requires_predicate`.
+Call `kb_model` with `mode: "analyze"`, then with `mode: "predicates"`. Apply a candidate only when its schema meaning and ordered arguments fit the claim. Use the returned `applyPlan` rather than hand-writing unsupported predicate names, and link the requirement to the predicate fact with `requires_predicate`.
 
 Treat the result as a Prolog-shaped ground term, not executable source: `predicate_name(arg1,...,argN)`. The selected `predicate_schema` fixes the name, arity, argument roles, and order. Store that model through `predicate_name`, `predicate_args`, `canonical_key`, and `polarity`; never interpolate prose into raw Prolog, introduce variables, or use a graph relationship such as `verified_by` as the predicate name.
 
@@ -84,15 +84,15 @@ The full logical representation of a requirement is the conjunction of all of it
 
 Treat the advisor's proposition status as a hard routing decision. `nonlogical`/`subjective` prose is not a logical claim: keep it as one observation when needed and do not add its key to `logic_claims`. `ambiguous` prose stays an ambiguity observation. `ontology_gap` prose stays unresolved unless an approved schema or validated Logic IR is available. Never split a subjective or commentary sentence into synthetic clauses just because it contains conditional words or domain vocabulary.
 
-If authorized input supplies `projectLocalSchemas`, use those signatures as the authority. Create the minimal `predicate_schema` endpoint before lookup, then rerun `kb_suggest_predicates` on the complete relation if the first lookup had no candidate. Apply exactly one ground predicate and one claim key for that relation. For `must not`, `never`, `cannot`, or `forbidden` wording, preserve the positive schema and set `polarity: deny`; do not turn the result into an asserted predicate or invent a negative name. An empty lookup before the declared schema exists is a retry condition, not proof of an ontology gap.
+If authorized input supplies `projectLocalSchemas`, use those signatures as the authority. Create the minimal `predicate_schema` endpoint before lookup, then rerun `kb_model` with `mode: "predicates"` on the complete relation if the first lookup had no candidate. Apply exactly one ground predicate and one claim key for that relation. For `must not`, `never`, `cannot`, or `forbidden` wording, preserve the positive schema and set `polarity: deny`; do not turn the result into an asserted predicate or invent a negative name. An empty lookup before the declared schema exists is a retry condition, not proof of an ontology gap.
 
 ## Typed rule lane
 
-Use a validated `kibi.logic.v1` object for a proposition whose meaning includes a condition, exception, obligation, prohibition, permission, quantifier, cardinality bound, or bounded temporal relation. `kb_model_requirement` returns the `rule_schema` and `rule` facts plus a `requires_rule` edge. The rule stores canonical JSON and a deterministic hash; any rendered Prolog is an audit view and is never executed. Reject raw goals, function symbols, cuts, meta-calls, dynamic predicates, I/O, unsafe variables, unstratified negation, and unbounded aggregation. Keep the exact proposition in `claim_text`, its advisor key in `claim_key`, and its byte span in the semantic ledger. Run `rule-safety` and `rule-verifiability` before treating the rule as modeled.
+Use a validated `kibi.logic.v1` object for a proposition whose meaning includes a condition, exception, obligation, prohibition, permission, quantifier, cardinality bound, or bounded temporal relation. `kb_model` with `mode: "requirement"` returns the `rule_schema` and `rule` facts plus a `requires_rule` edge. The rule stores canonical JSON and a deterministic hash; any rendered Prolog is an audit view and is never executed. Reject raw goals, function symbols, cuts, meta-calls, dynamic predicates, I/O, unsafe variables, unstratified negation, and unbounded aggregation. Keep the exact proposition in `claim_text`, its advisor key in `claim_key`, and its byte span in the semantic ledger. Run `rule-safety` and `rule-verifiability` before treating the rule as modeled.
 
 ### Strict scalar
 
-Claim: “Sessions expire after at most 30 minutes.” This is a scalar limit, not a predicate. Route it through `kb_model_requirement` to a subject plus `property_value` with `operator: lte`, `value_type: int`, and `value_int: 30`, linked by `constrains` and `requires_property`.
+Claim: “Sessions expire after at most 30 minutes.” This is a scalar limit, not a predicate. Route it through `kb_model` with `mode: "requirement"` to a subject plus `property_value` with `operator: lte`, `value_type: int`, and `value_int: 30`, linked by `constrains` and `requires_property`.
 
 ### Ambiguous claim
 

package/agent-plugin/skills/kibi-usage/resources/kb-improvement.md

@@ -19,7 +19,7 @@ are in `resources/fact-lanes.md` and the Predicate-First workflow in
 | Process or governance note | `meta` | usually `relates_to` |
 | Runtime or config gate | `flag` | `guards` |
 
-Call `kb_semantic_advisor` on the complete requirement body before encoding a
+Call `kb_model` with `mode: "analyze"` on the complete requirement body before encoding a
 clause. Apply a predicate only when a returned schema fits; otherwise leave an
 ontology-gap observation.