kibi-cursor 2.10.1 → 2.11.0

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "2.10.1",
+  "version": "2.11.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,80 @@
 # kibi-cursor
 
+## 2.11.0
+
+### Minor Changes
+
+- 4b4e7cb: A SWI-Prolog project can now prove its requirements against its own predicates. Exhaustive domains, `value_source` numbers, rule tables, state machines and patterns read `.pl` and `.plt` files with the SWI-Prolog Kibi already runs on, the same way they read TypeScript, JavaScript and Python exports, so a Prolog library no longer has to fall back to file patterns or a harness written in another language to reach `proved`. The kibi-usage skill (2.38.0) ships a `kibi_certificate` module (`resources/prolog-proofs.md`) that Prolog proof files use to write their certificates.
+
+  In a proof contract, `export` names a predicate indicator (`status/1`, `phrase//1`, `operators:operator/2`) and the new `arg` key on `domain_source` and `value_source` names the 1-based argument that holds the members of a predicate with more than one argument. A module file loads as its module and a plain file into `user`. Kibi refuses a read it cannot decide exactly: solutions that leave the argument unbound, more than 100,000 solutions, several arguments without `arg`, `arg` together with `field`, and `arg` on a TypeScript or Python export. A Prolog proof file imports its domain when it names the predicate and loads the file (`use_module`, `library(X)` for a pack's `prolog/` directory, `consult`, `ensure_loaded` or a `:- [...]` list), or when it is the `.plt` beside it. A rule predicate is called once per row and decided by success; a transition table is a predicate of arity 2 or 3 whose solutions are the edges, or a `next/3` predicate driven over its `domains`; a pattern is a single atom or string. One certificate reads one language, and a contract mixing languages is refused.
+
+  Code proof evaluation now goes through one evaluator per language, and a file in a language without an evaluator is refused with the language named. A code proof receipt is now also bound to the files of the symbols its contract reads (`domain_source`, `value_source`, `initial_source`, `pattern_source`, `domains`, `predicate_source`), so it goes stale when the file a domain is read from changes even when that symbol is not `covered_by` the test.
+
+  ## Migration
+
+  No files change shape. Code proof receipts whose contracts read a symbol outside the test's covered symbols get a new binding hash and need `kibi prove` once.
+
+- 79c86a7: Source proofs now read SWI-Prolog. The `references` reader accepts `.pl` and `.plt` files, so a Prolog pack can prove which libraries its modules load, which predicates they call (for example that nothing calls `use_foreign_library/1`), which environment variables they read and which errors they throw. A new `prolog` reader lists one argument of every fact with a given functor, such as the `requires/1` facts of `pack.pl`. Both read the files term by term with SWI-Prolog and never run the project's code. The kibi-usage skill (2.39.0) describes both readers.
+
+  `imports` lists each loaded file as written (`library(lists)`, `helpers`) from load directives and from load goals in clause bodies. `calls` lists `Name/Arity` (or `Module:Name/Arity`) of every goal in clause bodies and directives. It walks control constructs, grammar rules, lambdas and meta-predicate arguments, using the file's own `meta_predicate` declarations and SWI-Prolog's. `env` reads `getenv/2`, `string_args` reads the first argument of calls to `callee`, and `thrown` reads the error of `throw(error(type_error(...), _))` and the `library(error)` helpers. A rethrow of a caught ball does not count as a new error. Operators come from the file's own `op/3` directives, the module export lists it can read, and the SWI-Prolog libraries it loads.
+
+  Some reads cannot be decided statically, and Kibi refuses them with their file and line: a variable called as a goal or closure, a goal qualified by a variable module, a clause asserted from a variable, and conditional compilation. `property` is refused for Prolog files. The `prolog` reader takes `file`, `functor` (`Name/Arity`) and `arg`. It refuses a fact with several arguments when no `arg` is given, and a fact whose argument holds a variable. A list argument contributes its items. The read keeps its members in file order for `precedes` claims.
+
+  ## Migration
+
+  No files change shape. The source reader vocabulary now includes `prolog`.
+
+- f53950a: Source proofs now read Go, Java, C# and Rust. The `references` reader hands these files to `kibi-plugin-treesitter`, which lists what they import, call, read from the environment, pass as a first argument, throw and set as a property value, from their syntax trees and without compiling or running them. The kibi-usage skill (2.40.0) describes it.
+
+  A new plugin capability, `kibi.reference-extractor.v1` (kibi-plugin-sdk), lets a plugin answer the `references` reader for a language Kibi does not parse itself. A provider returns the members it reads exactly and an `unresolved` row (line and text) for each construct it cannot read statically, and Kibi refuses the read with those places. `validateReferenceExtractionResult` checks results. The capability activates only in `augment` mode.
+
+  `kibi-plugin-treesitter` provides it for Go, Java, C# and Rust, in the same bounded workers as symbol extraction. Members are written as the code names them: Go import paths, Java imports (`java.util.*`), C# `using` targets and Rust `use` paths expanded from their groups for `imports`; `os.Getenv`, `System.out.println` (and the method reference `System.out::println`), `Console.WriteLine` and `std::env::var` for `calls`, with `*.name` for a method on an expression Kibi cannot name; `os.Getenv`, `os.LookupEnv`, `System.getenv`, `Environment.GetEnvironmentVariable`, `env::var`, `env::var_os`, `env!` and `option_env!` for `env`; Go panics and Java and C# `throw new X()` for `thrown`; Go keyed literals and C# object, indexer and collection initializers for `property`. Names a file gives itself are followed: Go import aliases, Java single static imports, C# `using static` and `using X = ...` aliases and Rust `use` bindings (`use std::env::var as getvar`) read as the canonical name, and fully qualified forms (`java.lang.System.getenv`, `System.Environment.GetEnvironmentVariable`, `std::env::var`) match too: calls on `java.lang` and C# `System` types are listed under both spellings. C# `imports` also holds the project's `global using` lines, `<Using Include>` items and the usings `ImplicitUsings` adds, and `global::` prefixes are dropped. A function or method used as a value (`logf := logrus.Error`, a C# method group, a Rust path passed on) is listed in `calls`. A Go identifier that shadows a package the file does not import, and a Rust path whose root the file does not bind (a local `mod env`), are not taken for that package. A name computed at run time, the whole environment (including `os.ExpandEnv` and `Environment.ExpandEnvironmentVariables`), an environment getter handed on as a value (`g := os.Getenv`, `System::getenv`), a dot, static-wildcard or glob import that could bring a getter or call into scope, a call with no static name (`fs[0]()`, `<T as Tr>::m()`), reflection (also by fully qualified name, `Activator.CreateInstance` and Go `plugin`) and C# `dynamic` anywhere (for `calls` and `env` alike), a C# `#if` block, a Rust `#[cfg(...)]` item other than `#[cfg(test)]` (whose items are skipped), for Rust `calls` and `thrown` any macro invocation, attribute macro or derive outside the standard library, for Rust `env` a macro whose arguments mention a getter, and for `string_args` a macro whose arguments mention the callee fail the read with their place.
+
+  Proofs use a reference extractor only when its installed files match the release-qualified closure Kibi ships, the same check impact review applies, so an unqualified or modified provider is never imported. Without an active provider the read is refused with what to install. `kibi init`, `kibi doctor` and `kb_plan_bootstrap` suggest `kibi-plugin-treesitter` for symbols when sources in any of its languages are tracked, and for proofs when Go, Java, C# or Rust sources are tracked and it is not active for them, with the exact `kibi.plugins` entry to add; a project without a `package.json` creates one that only holds Kibi's plugin list and gitignores `node_modules/`. `kb_plan_bootstrap`'s source glob now also covers `.pyi`, `.cxx`, `.hh`, `.hxx`, `.cs`, `.sh`, `.bash`, `.tf` and `.hcl`.
+
+  `kibi-plugin-treesitter` 3.0 ships no grammars. Each grammar moved, unchanged, into its own data-only package, so a project downloads only the languages it uses and every language is installed the same way: `kibi-lang-python`, `kibi-lang-go`, `kibi-lang-rust`, `kibi-lang-java`, `kibi-lang-csharp`, `kibi-lang-php`, `kibi-lang-c`, `kibi-lang-cpp`, `kibi-lang-bash`, `kibi-lang-ruby`, `kibi-lang-hcl` (Terraform and HCL) and `kibi-lang-prolog` (SWI-Prolog), all at 1.0.0. JavaScript and TypeScript need no pack, since Kibi parses them itself. A pack holds the grammar WebAssembly and its license, with no code or install scripts. The plugin pins each pack's exact version and each grammar file's SHA-256 in `catalog.json` and lists the packs as optional peer dependencies in their major (`^1.0.0`); a worker checks the bytes before loading them. A file whose pack is missing (`TREESITTER_LANGUAGE_PACK_MISSING`) or another version (`TREESITTER_LANGUAGE_PACK_VERSION`) is now `unsupported` with the install line, and a modified grammar file is `failed` (`TREESITTER_LANGUAGE_PACK_MISMATCH`), for symbols and for references; neither is skipped. Packs resolve where Node finds them from the plugin (npm, pnpm and Bun; not Yarn Plug'n'Play). `kibi doctor` and `kibi init` name the packs the tracked sources need, and `kb_plan_bootstrap`'s plugin offer lists them in `alsoInstall`. `kibi doctor` also names an installed pack whose grammar does not match the pinned hash. While a pack is missing or another version, `kibi sync` warns once per file with the install line, and the staged check blocks a change to that file instead of asking for a whole-file review, so a missing install never disarms the gate.
+
+  Symbol signatures that told overloads apart wrongly are fixed: C++ `f(int&&)` no longer reads as `f(int&)`, a C/C++ variadic `...` and parenthesized declarators (`int (*p)`) are kept, C# `ref`, `out` and `in` parameters and `params` methods get their own signature, Java comments inside a parameter list no longer drop it, and a C++ function declarator inside a parameter or template parameter list is not reported as a symbol. Symbols whose locator changes this way need their `symbols.yaml` entry updated once.
+
+  A file the grammar reads only partly (a C `#include`, a Rust macro, a nested HCL block) no longer stops `kibi sync --refresh-symbol-coordinates` for the whole repository: symbols declared outside its uncovered ranges keep their coordinates, the others get none, and one warning per file names the lines and diagnostics. The staged check validates the same symbols and asks for a review only where a change touches an uncovered range. A file the analyzer cannot read as a whole (a syntax error, which the grammars also report for some valid code such as an `#ifdef` inside an `if`, a timeout or a changed grammar) gives only its own symbols no coordinates and is listed as a failed refresh; the rest of the repository still refreshes. Local gaps past the 64-diagnostic cap are summarized as one range instead of a whole-file limit, so large Terraform files keep their symbols. Kibi's own `.kb/` files are never analyzed as project source, so they no longer ask for kibi-lang-prolog, and a `.pl` file alone (often Perl) no longer counts as Prolog for the pack suggestion.
+
+  The `references` readers refuse more constructs they cannot read exactly, so a claim such as "never calls X" or "reads no environment variable" can no longer pass on code that does. Go resolves a local `os` (parameter, block, `range`, type switch) and a non-standard package imported as `os` by scope, refuses cgo, `//go:linkname` and `.Environ()` for `env`, and lists a method on a receiver that visibly comes from package p also as `p.M`. Java follows receivers by declared type, cast and `new`, reads imports with comments, does not take `import other.System` or a `System` class declared in the file for `java.lang.System`, and refuses `getenv`, `exit`, `halt`, `exec`, `load` and `loadLibrary` on a receiver of unknown type. C# files a bare call under a type only when the file declares it or one known `using static` type has it, and refuses other bare calls and getters it cannot place; `@` verbatim identifiers are read without the `@`. Rust resolves paths through `use`, `mod` and `extern crate` in scope (`use Command as C`, `self::`, `extern crate std as s`) and refuses `env`, `imports` and `string_args` on macros outside the standard library and common formatting macros, `include!`, a nested `env!` and attributes configured with `env`. Kibi's Python reader follows import aliases for `env` and `calls`, reads `os.environ.setdefault`, `pop` and `in`, lists `from urllib import request` as `urllib.request` too, and refuses the whole environment handed on or copied, `getattr` on an imported module, `exec`, `eval`, `__import__`, `importlib.import_module`, `sys.modules` and star imports. Kibi's Prolog reader no longer fails on `meta_predicate` declarations, reads `apply/2` and literal `assertz` clauses, refuses `term_expansion` and `goal_expansion` in the files and in project files they load, refuses an `include` of a file outside `files`, and fails instead of silently dropping a loaded file it cannot read.
+
+  A `references` claim is decided only where it holds. Reference members are matched by name segment (`.`, `/`, `::`), so `excludes` fails on a member under an excluded item (`java.sql` excludes `java.sql.Connection`, `github.com/labstack/echo/v4` excludes `.../echo/v4/middleware`), on the prefix of an item ending in `*` (`java.sql.*`, `os.*`), and, with the member, the item and the files named, on a member that may be the item: a wildcard import, a shorter name (`File.delete`) or a call on a receiver Kibi cannot name (`*.delete` may be `java.io.File.delete`). `includes` and `subset_of` count only members that certainly are an item, so `*.m` never satisfies `X.m` and `os` does not allow `os/exec`. A source proof is rejected when a symbol the test covers or that implements the claim's requirement lies in a file the read does not cover, and the refusal for files the reader cannot read no longer advises dropping them from `files`: it says the claim cannot be decided for them. An `eq`, `subset_of` or `excludes` claim read with `string_args` on an environment getter (`os.Getenv`, `env::var_os`, `System.getenv`, `getenv/2`, ...) is refused with a pointer to `extract: env`.
+
+  Failures that looked like success are now reported. `kibi doctor` fails when a plugin `package.json#kibi.plugins` declares is not installed, and when the installed `kibi-plugin-treesitter` is not the release-qualified build this Kibi pins (such as an older build published under the same version), naming the fix. `kibi sync --refresh-symbol-coordinates` refuses, keeping the stored coordinates, instead of dropping them and reporting success. A symbol Kibi cannot place in its existing source file is reported by `kibi check` (advisory `symbol-coordinates-missing`, a warning) and by `kb_upsert`. `kibi prove` counts a test whose certificate or claim binding was rejected as `refused`, not `passed` (a `refused` field in its summary), and says when a derived binding cannot prove the claim because the receipt is not end to end; `kibi proof explain` and signoff list each claim's bindings and rejections whatever the requirement's proof status, and say why a derived claim is not yet proved.
+
+  C and C++ headers are read as the compiler reads them: an include guard (`#ifndef G` / `#define G` ... `#endif`), the `#ifdef __cplusplus` / `extern "C" {` linkage guard and an `#if 0` block are blanked before parsing, keeping every line and column, so guarded headers keep their symbol coordinates and a header edit no longer blocks the commit. Terraform nested blocks (`validation`, `lifecycle`, `dynamic`, `ingress`) belong to the block that holds them and are no longer analysis gaps, and `moved`, `import`, `removed` and `check` blocks are neither symbols nor gaps. Past the 64-diagnostic cap, local gaps are merged into the fewest ranges that fit, closing first the gaps between them that hold no symbol start, so declarations between gap groups keep their coordinates instead of one range covering the rest of the file.
+
+  ## Migration
+  - Install the grammar packs for the languages you analyze next to the plugin, for example `npm install --save-dev kibi-plugin-treesitter@3 kibi-lang-python kibi-lang-go`. Python and SWI-Prolog need their packs too (`kibi-lang-python`, `kibi-lang-prolog`); until they are installed, symbol extraction for those files is unsupported, while Kibi's own Python and Prolog source-proof readers keep working. `kibi doctor` prints the exact line for the tracked sources. Until the packs are installed, those files are reported as unsupported instead of analyzed.
+  - Re-check `excludes` reference claims written against a parent name or with a trailing `*`: they now fail on members under it, and claims over files with `*.m` calls or short names that may be an excluded item are refused. A proof whose test covers, or whose requirement is implemented by, a symbol outside `files` is rejected until those files are read. Rewrite environment claims read with `string_args` on a getter to `extract: env`. Scripts that read `kibi prove`'s `passed` count now see refused tests under `refused`.
+  - To prove references in Go, Java, C# or Rust, also add `"kibi.reference-extractor.v1": { "mode": "augment" }` to the `kibi-plugin-treesitter` entry of `package.json#kibi.plugins`.
+
+### Patch Changes
+
+- Each hook decision is now recorded in usage telemetry, as on the other hosts (`KIBI_TELEMETRY=0` turns it off). The README npm copy route replaces an earlier copy instead of nesting into it and explains that the copy needs no `node_modules`, and the missing-`kibi-mcp` error says how to use a global `kibi-mcp` through the manual MCP entry.
+
+- The kibi-usage skill (2.40.1) describes the `must keep true` line of edit snippets as the requirement's modeled claims or its own statement.
+
+- Edit snippets say what the lead requirement must keep true as the claims its facts model, in words with their operator and members (for example "REQ-GREET must keep true: The greet function must not call console.log."), or as the requirement's own statement, instead of listing internal fact IDs and subject keys. A requirement title that an older Kibi cut at a dot inside a name is shown whole.
+
+- 048d1c9: Close false proofs found by testing the language packs before release:
+  - A references claim whose subject key or claim text names a project file (also with a repository prefix, another letter case, no extension, or spaces) is rejected unless that file is among the files read, so a claim about one file cannot be decided on another.
+  - `excludes` now fails on a longer name ending in the excluded item at a segment boundary (`checkNotNull` excludes `Preconditions.checkNotNull`).
+  - Rust raw identifiers (`std::r#env::var`) are read as their plain names.
+  - C# method groups handed on as values (`Environment.Exit` in a switch arm, `??`, `yield return`, a lambda body, `!`) count as calls, as does a method group on any receiver (`Process.GetCurrentProcess().Kill`); an `Environment` that is not provably `System.Environment` (pattern or `out` variable, type parameter, primary-constructor parameter, alias, a project type) refuses or is read as what it binds.
+  - Go: env reads through a helper or variable in another file of the package, or in another package of the project, refuse; a package imported under a well-known name (`logrus`, `exec`) is listed by its import path.
+  - Java: a `System` class of the same package in another source root refuses `System` reads.
+  - Python: references through a module's private name (`from tempfile import _os`), reflection on a module (`getattr`, `vars`, a module assigned to a name) and ctypes or cffi refuse; `posix.X` and `nt.X` are read as `os.X`.
+  - SWI-Prolog: goals in `'~@'` message lines and in grammar bodies passed to `phrase`/`call_dcg` are read; an aliased include resolves only through the `file_search_path` declarations read, never by path suffix, and include refusals name the file to add to `files:` only when it is the exact resolution.
+  - The Cursor hook runner is a self-contained bundle, so a copied or GitHub-installed plugin no longer fails with `ERR_MODULE_NOT_FOUND`.
+  - Plugins accept kibi-plugin-sdk 0.6 as a peer.
+
+- f9ec786: Usage telemetry events now carry a `channel`: `release` for an installed Kibi package, `source` when Kibi runs from a checkout of its own repository, or the value of `KIBI_TELEMETRY_CHANNEL` when a harness sets one (for example `agent-test`). Development and test runs can then be filtered out of real usage. Nothing else about what is sent changes.
+- Updated dependencies [f9ec786]
+  - kibi-agent-core@0.11.1
+
 ## 2.10.1
 
 ### Patch Changes

package/README.md

@@ -46,12 +46,20 @@ On WSL workspaces, Cursor reads `~/.cursor/plugins/local` in your Linux home, no
 npm install --save-dev kibi-cursor
 ```
 
-Copy the installed package into Cursor's local plugin directory (do not symlink):
+Copy the installed package into Cursor's local plugin directory (do not
+symlink). Remove an earlier copy first, or `cp` nests the new one inside it:
 
 ```bash
-cp -r "$(npm root)/kibi-cursor" ~/.cursor/plugins/local/kibi-cursor
+mkdir -p ~/.cursor/plugins/local
+rm -rf ~/.cursor/plugins/local/kibi-cursor
+cp -R "$(npm root)/kibi-cursor" ~/.cursor/plugins/local/kibi-cursor
 ```
 
+The copy needs no `node_modules`: the hooks run `bin/hook-runner.mjs`, a
+self-contained bundle, and the MCP launcher `bin/launch-kibi-mcp.mjs` uses
+only Node built-ins and starts the opened project's own `kibi-mcp`. Copy again
+after upgrading `kibi-cursor`.
+
 ## MCP configuration
 
 The plugin bundles `mcp.json` with a thin launcher that locates and starts the
@@ -81,6 +89,16 @@ Toggle the bundled MCP server from **Settings → Features → Model Context Pro
 Cursor expands `${CURSOR_PLUGIN_ROOT}` to the installed plugin directory and
 `${workspaceFolder}` to the opened workspace before starting the command.
 
+Unlike the Claude Code, Codex and ZCode launchers, which fall back to a
+global `kibi-mcp` (with a notice on stderr), the Cursor plugin launcher only
+runs the opened project's own `kibi-mcp`: Cursor starts plugin MCP servers
+from a host-chosen directory, and a project-local package keeps the server
+version tied to the project's `kibi-cli` and `.kb/` schema. Without one it
+refuses with an error that says how to install it. To use a global
+`kibi-mcp` anyway, turn off the plugin's MCP server and add the manual entry
+below (`npx --no-install` finds a project-local install first, then a global
+one).
+
 Manual MCP fallback (no plugin install required):
 
 ```json
@@ -119,7 +137,7 @@ agent-plugin/
 
 ### Advisory editor hooks
 
-Hooks are warning-only and never replace MCP/CLI behavior:
+Hooks are warning-only and never replace MCP/CLI behavior. `hooks/hooks.json` runs `bin/hook-runner.mjs`, a committed self-contained bundle (with `kibi-agent-core` inlined), so a copied plugin directory or a GitHub marketplace install runs the hooks without `node_modules` or a build step:
 
 - **sessionStart**: bootstrap reminder when `.kb/manifest.json` is missing.
 - **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. When the edited code implements a firm requirement (a rule the person set), the message first tells the agent to ask the person before an edit that breaks it, once per requirement per conversation (Cursor does not enforce a hook's "ask"; `KIBI_CONFIRM_FIRM_EDITS=0` turns this off).

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.10.1",
+  "version": "2.11.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://looted.github.io/kibi/",

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.37.0
+version: 2.40.1
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -20,6 +20,7 @@ resources:
   - resources/fact-lanes.md
   - resources/workflows.md
   - resources/proof.md
+  - resources/prolog-proofs.md
   - resources/ui-requirements.md
   - resources/logic-ir.md
   - resources/kb-improvement.md
@@ -94,8 +95,10 @@ it is a pointer to the knowledge, never proof. Each line answers one question:
   requirement first. Read the lead requirement with `kb_query({id})` before
   changing behavior; add `includeBody: true` to see its authored prose, and
   fix a stale sentence there with `kb_upsert` `document.body`.
-- `REQ-… must keep true: FACT-…` (edit only): the ground facts the lead
-  requirement requires. An edit that breaks one of them is a requirement
+- `REQ-… must keep true: <claim>` (edit only): what the lead requirement
+  requires, as the claims its facts model (with the operator and members,
+  such as "The greet function must not call console.log") or, without
+  them, its own statement. An edit that breaks one of them is a requirement
   change: ask before changing the rule (see Decision firmness), and never
   code around the fact.
 - `Decision: ADR-…` (edit only): the decision behind the lead requirement.

package/agent-plugin/skills/kibi-usage/resources/prolog-proofs.md

@@ -0,0 +1,207 @@
+# SWI-Prolog Code Proofs
+
+Kibi reads code models from SWI-Prolog files (`.pl`, `.plt`) with the
+SWI-Prolog it runs on (KIBI_SWIPL, the bundled runtime, then `swipl` on
+PATH). It loads the file a symbol names (a module, or a plain file into
+`user`) and reads a predicate named by its indicator, the symbol's title
+(`operator/2`, `lists:append/3`, `greeting//1`) or `export`.
+
+- A domain (`exhaustive`, `domains`, `value_source` with `measure: count`)
+  is the distinct solutions of one argument. A one-argument predicate needs
+  nothing more; for more arguments set `arg` (1-based) to the one that names
+  each member: `domain_source: {symbol_id: SYM-operator, arg: 1}` lists every
+  `Name` of `operator(Name, Description)`. A solution that leaves that
+  argument unbound refuses the read.
+- A value (`value_source`) is the single number a constant holds:
+  `hard_limit_seconds(10).` Zero or several solutions refuse the read.
+- A `rule` predicate is called once per row of its argument domains; success
+  is true, failure false, an exception an error row (which rejects).
+- A `state_machine` transition table is a `Name/2` (from, to) or `Name/3`
+  (from, event, to) fact table: every solution is an edge. With `domains:
+  {state, event}` a `Name/3` next-state predicate is called on every state
+  and event. `initial_source` names an `initial/1`-style fact.
+- A `regex` reads an atom or string constant as a `type: string` pattern;
+  Kibi decides string facts on it. Patterns for `library(pcre)` are not read.
+
+Loading a module runs its directives, the same trust a JavaScript import
+gives. The proof file must name the predicate and load its file
+(`use_module`, `ensure_loaded`, `consult`, a `:- [..]` load list, or
+`library(X)` for a pack's `prolog/X.pl`), or be the plunit `.plt` file
+beside it; otherwise Kibi treats the domain as hand-listed. `arg` on a
+TypeScript, JavaScript or Python export is refused, and so is `field` on a
+Prolog predicate.
+
+## Writing the certificate
+
+A Prolog test writes the `kibi.code-certificate.v1` JSON into the directory
+`kibi prove` sets in `KIBI_PROOF_CERTIFICATES`. Copy this module into the
+project's test directory (for example `test/kibi_certificate.pl`) and call it
+from the proof. Read members from the code with `findall/3` over the domain
+predicate; never list them by hand.
+
+```prolog
+:- module(kibi_certificate,
+          [ kibi_exhaustive_certificate/5,  % +TestId, +SymbolId, +Members, :Check, -Certificate
+            kibi_rule_certificate/4,        % +TestId, +Domains, +Predicates, -Certificate
+            kibi_machine_certificate/5,     % +TestId, +SymbolId, +Edges, +Initial, -Certificate
+            kibi_pattern_certificate/4,     % +TestId, +SymbolId, +Text, -Certificate
+            kibi_write_certificate/1        % +Certificate
+          ]).
+:- use_module(library(http/json)).
+:- use_module(library(apply)).
+:- use_module(library(lists)).
+
+:- meta_predicate
+    kibi_exhaustive_certificate(+, +, +, 1, -).
+
+% Members as Kibi reads them: atoms and strings as text, numbers as written,
+% other terms quoted.
+kibi_text(Value, Text) :- string(Value), !, Text = Value.
+kibi_text(Value, Text) :- atom(Value), !, atom_string(Value, Text).
+kibi_text(Value, Text) :- number(Value), !, number_string(Value, Text).
+kibi_text(Value, Text) :- format(string(Text), "~q", [Value]).
+
+%!  kibi_exhaustive_certificate(+TestId, +SymbolId, +Members, :Check, -Certificate)
+%
+%   Run Check on every member of the domain and record each outcome. Read
+%   Members from the code (findall over the domain predicate), never list
+%   them by hand: Kibi re-reads the predicate and rejects a different set.
+kibi_exhaustive_certificate(TestId, SymbolId, Members, Check, Certificate) :-
+    maplist(kibi_text, Members, Texts),
+    maplist(exhaustive_result(Check), Members, Texts, Results),
+    Certificate = _{version: "kibi.code-certificate.v1", kind: "exhaustive",
+                    test_id: TestId,
+                    domain: _{symbol_id: SymbolId, members: Texts},
+                    results: Results}.
+
+exhaustive_result(Check, Member, Text, Result) :-
+    catch(( call(Check, Member)
+          -> Result = _{member: Text, outcome: "passed"}
+          ;  Result = _{member: Text, outcome: "failed", message: "the check failed"}
+          ),
+          Error,
+          ( message_to_text(Error, Message),
+            Result = _{member: Text, outcome: "failed", message: Message} )).
+
+%!  kibi_rule_certificate(+TestId, +Domains, +Predicates, -Certificate)
+%
+%   Domains is a list of domain(Type, SymbolId, Members); Predicates a list
+%   of predicate(Name, SymbolId, ArgTypes, Goal), where Goal is called with
+%   one argument per type appended and decides the row by success or
+%   failure.
+kibi_rule_certificate(TestId, Domains, Predicates, Certificate) :-
+    findall(Type-_{symbol_id: SymbolId, members: Texts},
+            ( member(domain(Type, SymbolId, Members), Domains), maplist(kibi_text, Members, Texts) ),
+            DomainPairs),
+    dict_pairs(DomainDict, _, DomainPairs),
+    findall(Name-_{symbol_id: SymbolId, arg_types: ArgTypes, rows: Rows},
+            ( member(predicate(Name, SymbolId, ArgTypes, Goal), Predicates),
+              maplist(domain_members(Domains), ArgTypes, Lists),
+              findall(Row, (maplist(member, Tuple, Lists), rule_row(Goal, Tuple, Row)), Rows)
+            ),
+            PredicatePairs),
+    dict_pairs(PredicateDict, _, PredicatePairs),
+    Certificate = _{version: "kibi.code-certificate.v1", kind: "rule",
+                    test_id: TestId, domains: DomainDict, predicates: PredicateDict}.
+
+domain_members(Domains, Type, Members) :-
+    memberchk(domain(Type, _, Members), Domains).
+
+rule_row(Goal, Tuple, Row) :-
+    maplist(kibi_text, Tuple, Args),
+    Call =.. [call, Goal|Tuple],
+    catch(( once(Call) -> Row = _{args: Args, value: true} ; Row = _{args: Args, value: false} ),
+          Error,
+          ( message_to_text(Error, Message), Row = _{args: Args, error: Message} )).
+
+%!  kibi_machine_certificate(+TestId, +SymbolId, +Edges, +Initial, -Certificate)
+%
+%   Edges is the list of From-To pairs of the transition table (findall over
+%   it); Initial is the list of initial states, or [] when the contract names
+%   no initial_source.
+kibi_machine_certificate(TestId, SymbolId, Edges, Initial, Certificate) :-
+    findall([F, T], (member(From-To, Edges), kibi_text(From, F), kibi_text(To, T)), Pairs0),
+    sort(Pairs0, Pairs),
+    findall(S, (member([A, B], Pairs), member(S, [A, B])), Ends),
+    sort(Ends, States),
+    Machine0 = _{symbol_id: SymbolId, states: States, transitions: Pairs},
+    (   Initial == []
+    ->  Machine = Machine0
+    ;   maplist(kibi_text, Initial, InitialTexts0),
+        sort(InitialTexts0, InitialTexts),
+        Machine = Machine0.put(initial, InitialTexts)
+    ),
+    Certificate = _{version: "kibi.code-certificate.v1", kind: "state_machine",
+                    test_id: TestId, machine: Machine}.
+
+%!  kibi_pattern_certificate(+TestId, +SymbolId, +Text, -Certificate)
+%
+%   The string or atom constant a string claim is about.
+kibi_pattern_certificate(TestId, SymbolId, Value, Certificate) :-
+    kibi_text(Value, Text),
+    Certificate = _{version: "kibi.code-certificate.v1", kind: "regex", test_id: TestId,
+                    pattern: _{symbol_id: SymbolId, type: "string", value: Text}}.
+
+%!  kibi_write_certificate(+Certificate)
+%
+%   Leave the certificate where kibi prove reads it (the directory in
+%   KIBI_PROOF_CERTIFICATES). Does nothing outside a kibi prove run.
+kibi_write_certificate(Certificate) :-
+    (   getenv('KIBI_PROOF_CERTIFICATES', Directory), Directory \== ''
+    ->  make_directory_path(Directory),
+        format(atom(Name), "~w.json", [Certificate.test_id]),
+        directory_file_path(Directory, Name, File),
+        setup_call_cleanup(open(File, write, Out, [encoding(utf8)]),
+                           json_write_dict(Out, Certificate, [width(0)]),
+                           close(Out))
+    ;   true
+    ).
+
+message_to_text(Error, Text) :-
+    catch(message_to_codes(Error, Text), _, fail), !.
+message_to_text(Error, Text) :- format(string(Text), "~q", [Error]).
+
+message_to_codes(Error, Text) :-
+    '$messages':translate_message(Error, Lines, []),
+    with_output_to(string(Raw), print_message_lines(current_output, '', Lines)),
+    split_string(Raw, "", "\n ", [Text]).
+```
+
+A proof that the operators are exactly the claimed set:
+
+```prolog
+:- use_module('../prolog/operators').
+:- use_module(kibi_certificate).
+:- initialization(main, main).
+
+main :-
+    findall(Name, operator(Name, _), Names0),
+    list_to_set(Names0, Names),
+    kibi_exhaustive_certificate('TEST-operator-set', 'SYM-operator', Names,
+                                [Name]>>operator(Name, _), Certificate),
+    kibi_write_certificate(Certificate).
+```
+
+Its contract: `kind: exhaustive`, `domain_source: {symbol_id: SYM-operator,
+arg: 1}`, `proves: [CLAIM-...]`. A rule proof passes
+`[domain(status, 'SYM-status', Statuses)]` and
+`[predicate(detected, 'SYM-detected', [status], detected)]`; its contract
+names `predicate_source: {detected: {symbol_id: SYM-detected}}` and
+`domains: {status: {symbol_id: SYM-status}}`.
+
+## Source proofs over Prolog code
+
+A `source` proof needs no certificate: Kibi reads the Prolog files itself,
+term by term, and never runs them. Use the `references` reader on `.pl` and
+`.plt` files for what modules load (`extract: imports`, members as written:
+`library(lists)`, `helpers`), call (`calls`, `Name/Arity` or
+`Module:Name/Arity`), read from the environment (`env`, `getenv/2`), pass as
+a first argument (`string_args` with `callee`) and throw (`thrown`: the error
+of `error(type_error(...), _)` is `type_error`). Use the `prolog` reader for
+facts: `{reader: prolog, file: pack.pl, functor: requires/1}` lists a pack's
+requirements, and `arg` picks the argument of a fact with several. A goal or
+closure held in a variable (`call(Goal)`, `maplist(G, L)`), a goal with a
+variable module, a clause asserted from a variable and `:- if(...)` fail the
+read with their place: name the predicate instead. The claim cannot be
+decided for a file the read refuses; never drop a file the claim is about
+from `files`.

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

@@ -262,11 +262,15 @@ left:
   each list item, such as the `run` of each workflow step), `glob` (`pattern`, `capture`),
   `openapi` (`file`, `select: operations|unsecured_operations|...`),
   `references` (`files`, `extract: env|imports|calls|string_args|thrown|
-  property`), `schema` (`format: drizzle|prisma|sql`, `select:
+  property`; TypeScript, JavaScript, Python and SWI-Prolog files, and Go,
+  Java, C# and Rust files through `kibi-plugin-treesitter`), `schema` (`format: drizzle|prisma|sql`, `select:
   tables|columns|required_columns|nullable_columns|foreign_keys`), `routes`
   (Hono or Express app export, `path_prefix`, `names_from`, `select:
   routes|middleware`) or `validator` (zod, valibot or pydantic, `select:
-  fields|required_fields|optional_fields`). A member Kibi cannot read
+  fields|required_fields|optional_fields`) or `prolog` (`file`, `functor:
+  requires/1`, `arg`: one argument of each fact, such as a pack's
+  requirements in `pack.pl`). Prolog files are read term by term and never
+  run; see `resources/prolog-proofs.md`. A member Kibi cannot read
   statically (a computed env name, a dynamic import, an env object handed
   to a variable) fails the read with its location, and so does an empty
   read (a glob matching no file, migrations with no `CREATE TABLE`), so a
@@ -288,6 +292,40 @@ left:
   The builders need kibi-cli 2.33.0 or newer in the project. The env
   extractor reads `process.env`, `import.meta.env`, `Bun.env`,
   `Deno.env.get`, `os.environ` and `os.getenv`, through casts.
+- `references` over Go, Java, C# or Rust needs `kibi-plugin-treesitter` and
+  the language's grammar pack (`kibi-lang-go`, `kibi-lang-java`,
+  `kibi-lang-csharp`, `kibi-lang-rust`) in `devDependencies`, with the
+  plugin activated for proofs:
+  `"kibi.reference-extractor.v1": { "mode": "augment" }` in its
+  `kibi.plugins` entry (next to `"kibi.symbol-extractor.v2"`). A project
+  with no `package.json` creates one that only holds this list. Without it
+  the read is refused with what to install, so ask the operator before
+  installing; `kibi doctor` names what the project needs. Members are
+  written as the code names them (`os.Getenv`, `System.out.println`,
+  `Console.WriteLine`, `std::env::var`, Go import paths, `java.util.*`,
+  `std::io::Write`); a method on an expression Kibi cannot name is
+  `*.name`. Reflection, a name computed at run time, the whole
+  environment, C# `dynamic` and `#if`, Rust `#[cfg(...)]` items other than
+  `#[cfg(test)]`, and any macro for Rust `calls` and `thrown` fail the
+  read with their place: the claim cannot be decided for that file, so
+  model a claim the code can show (Rust `calls` over a file with
+  `println!` is always refused). Never drop a file the claim is about
+  from `files`: the read decides a claim only for the files it covers,
+  and a proof is rejected when a symbol the test covers or that
+  implements the claim's requirement lies outside them.
+- Reference members match by name segments (`.`, `/`, `::`). `excludes`
+  fails on anything that is or may be an excluded item: `java.sql`
+  excludes `java.sql.Connection`, `github.com/labstack/echo/v4` excludes
+  `.../echo/v4/middleware`, a trailing `*` is a prefix (`java.sql.*`), a
+  wildcard import or a shorter name (`File.delete`) may be the item, and
+  `*.delete` (a call on a receiver Kibi cannot name) may be
+  `java.io.File.delete`, so the claim is refused naming it. `includes` and
+  `subset_of` count only members that certainly are an item (the item, a
+  member under `X.*`, or `a.b.m` for `*.m`); `eq` compares spellings.
+- For a claim about what the code reads from the environment use
+  `extract: env`: `string_args` on a getter (`os.Getenv`, `env::var`,
+  `System.getenv`, `getenv/2`, ...) sees only that getter, so Kibi refuses
+  it for `eq`, `subset_of` and `excludes`.
 
 `arithmetic` and `smt` from `constraint_source` alone prove that the
 knowledge base's facts entail the claim, not that code follows the facts:
@@ -318,7 +356,10 @@ read for a test that wants to assert on it), fail the test when it records a fai
 (`failedMembers`, `failedCalls`), and call `writeCodeCertificate`; it writes to the
 directory `kibi prove` sets in `KIBI_PROOF_CERTIFICATES` and does nothing
 elsewhere. A Python test writes the same `kibi.code-certificate.v1` JSON
-to that directory itself. Wire the KB: the proof file symbol is
+to that directory itself. Kibi also reads SWI-Prolog domains, constants,
+rule predicates, transition tables and string constants (`arg` picks a
+predicate's argument); `resources/prolog-proofs.md` has the rules and a
+certificate module to copy. Wire the KB: the proof file symbol is
 `executable_for` the test and named in `required_proofs`; the domain symbol
 (and every symbol a rule, machine or pattern contract names) `implements`
 the requirement and is `covered_by` the test; the test