kibi-cli 2.39.0 → 2.40.0

package/dist/public/proof-sources.js

@@ -21,8 +21,9 @@
  * JSON or YAML file, the files a glob matches, an OpenAPI document, the
  * references the code makes (environment variables, imports, calls, string
  * arguments, thrown error codes, property values), a data schema (drizzle,
- * Prisma or SQL migrations), a web app's route table (Hono, Express) and a
- * validator object (zod and anything with safeParse).
+ * Prisma or SQL migrations), a web app's route table (Hono, Express), a
+ * validator object (zod and anything with safeParse) and the facts of a
+ * SWI-Prolog file (a pack's requires/1).
  *
  * Every reader is exact or refuses: a member Kibi cannot read statically (a
  * computed environment variable name, a dynamic import, an ALTER TABLE form
@@ -44,6 +45,7 @@ export const SOURCE_READERS = [
     "schema",
     "routes",
     "validator",
+    "prolog",
 ];
 const SELECTS = {
     json: ["keys", "values", "items"],
@@ -89,6 +91,7 @@ const KEYS = {
         "select",
     ],
     validator: ["reader", "file", "export", "select"],
+    prolog: ["reader", "file", "functor", "arg"],
 };
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value)
@@ -221,6 +224,15 @@ export function sourceSpecErrors(value, label) {
             if (!nonEmpty(row.export))
                 errors.push(`${label}.export is required for reader validator: name the object schema`);
             break;
+        case "prolog":
+            file("file", true);
+            if (typeof row.functor !== "string" ||
+                !/^[a-z][A-Za-z0-9_]*\/(?:0|[1-9][0-9]*)$/.test(row.functor))
+                errors.push(`${label}.functor is required for reader prolog: name the facts read as Name/Arity (requires/1)`);
+            if (row.arg !== undefined &&
+                !(Number.isInteger(row.arg) && row.arg >= 1))
+                errors.push(`${label}.arg must be the 1-based argument of each fact that holds the member`);
+            break;
     }
     return errors;
 }
@@ -245,14 +257,28 @@ function globList(value) {
 const DEFAULT_IGNORE = ["**/node_modules/**", "**/.git/**", "**/.kb/**"];
 /** Workspace-relative files a glob list matches, sorted. */
 // implements REQ-kibi-source-proof-kinds
-export function matchWorkspaceFiles(workspaceRoot, patterns, ignore = []) {
+export function matchWorkspaceFiles(workspaceRoot, patterns, ignore = [], caseSensitive = true) {
+    // A symbolic link to a file is read as that file (git and compilers read
+    // it so); links to folders are not walked.
     return fg
         .sync([...patterns], {
         cwd: workspaceRoot,
         ignore: [...DEFAULT_IGNORE, ...ignore],
+        caseSensitiveMatch: caseSensitive,
         dot: true,
-        onlyFiles: true,
+        onlyFiles: false,
+        markDirectories: true,
         followSymbolicLinks: false,
+    })
+        .filter((file) => {
+        if (file.endsWith("/"))
+            return false;
+        try {
+            return statSync(path.join(workspaceRoot, file)).isFile();
+        }
+        catch {
+            return false;
+        }
     })
         .map((file) => file.split(path.sep).join("/"))
         .sort();
@@ -323,6 +349,9 @@ export function sourceDependencies(workspaceRoot, spec) {
             for (const file of globList(spec.names_from))
                 addFile(file);
             break;
+        case "prolog":
+            addFile(String(spec.file));
+            break;
     }
     if (spec.reader === "routes" ||
         spec.reader === "validator" ||
@@ -1275,6 +1304,14 @@ export async function readSource(workspaceRoot, spec, evaluate) {
             ok: true,
             model: { members: sortedUnique(evaluated.members ?? []) },
         };
+    if (spec.reader === "prolog")
+        return {
+            ok: true,
+            model: {
+                members: sortedUnique(evaluated.members ?? []),
+                sequence: evaluated.sequence ?? [],
+            },
+        };
     if (spec.reader === "routes") {
         const routes = selectedRoutes(spec, evaluated.routes ?? []).sort((a, b) => `${a.path} ${a.method}` < `${b.path} ${b.method}` ? -1 : 1);
         if (typeof spec.path_prefix === "string" && routes.length === 0)
@@ -1306,6 +1343,8 @@ export function describeSource(spec) {
             return `routes of ${spec.export} in ${spec.file}${spec.path_prefix ? ` under ${spec.path_prefix}` : ""}`;
         case "validator":
             return `validator ${spec.export} in ${spec.file}`;
+        case "prolog":
+            return `${spec.functor} facts in ${spec.file}${spec.arg ? ` (argument ${spec.arg})` : ""}`;
     }
 }
 /** Unresolved references, as one rejection reason naming the first few. */

package/dist/public/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/dist/public/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/dist/public/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

package/dist/schemas/entity.schema.json

@@ -833,7 +833,7 @@
                 },
                 "source": {
                     "type": "object",
-                    "description": "source: the project source a source proof reads. A project source Kibi reads by itself. reader json or yaml: {file, path?, select?: keys|values|items}. glob: {pattern, capture?, ignore?} (capture true reads what each * matched). openapi: {file, select?: operations|unsecured_operations|security_schemes|responses}. references: {files, extract: env|imports|calls|string_args|thrown|property, callee?, key?, ignore?}. schema: {format: drizzle|prisma|sql, file (drizzle, prisma) or files (sql migrations), exports?, table?, select?: tables|columns|required_columns|nullable_columns|foreign_keys}. routes: {file, export, framework?: hono|express, path_prefix?, names_from?, select?: routes|middleware}. validator: {file, export, select?: fields|required_fields|optional_fields}. Paths are repository-relative. A member Kibi cannot read statically fails the read with its location.",
+                    "description": "source: the project source a source proof reads. A project source Kibi reads by itself. reader json or yaml: {file, path?, select?: keys|values|items}. glob: {pattern, capture?, ignore?} (capture true reads what each * matched). openapi: {file, select?: operations|unsecured_operations|security_schemes|responses}. references: {files, extract: env|imports|calls|string_args|thrown|property, callee?, key?, ignore?} over TypeScript, JavaScript, Python and SWI-Prolog files. schema: {format: drizzle|prisma|sql, file (drizzle, prisma) or files (sql migrations), exports?, table?, select?: tables|columns|required_columns|nullable_columns|foreign_keys}. routes: {file, export, framework?: hono|express, path_prefix?, names_from?, select?: routes|middleware}. validator: {file, export, select?: fields|required_fields|optional_fields}. prolog: {file, functor: Name/Arity, arg?} reads one argument of every fact with that functor in a SWI-Prolog file (requires/1 in pack.pl), without running it. Paths are repository-relative. A member Kibi cannot read statically fails the read with its location.",
                     "required": [
                         "reader"
                     ],
@@ -848,7 +848,8 @@
                                 "references",
                                 "schema",
                                 "routes",
-                                "validator"
+                                "validator",
+                                "prolog"
                             ]
                         }
                     },
@@ -874,6 +875,11 @@
                             "type": "string",
                             "minLength": 1,
                             "description": "exhaustive: when the export is a list of records, the field of each record that names a domain member (a catalog's name)."
+                        },
+                        "arg": {
+                            "type": "integer",
+                            "minimum": 1,
+                            "description": "A SWI-Prolog predicate's argument (1-based) whose solutions Kibi reads, when the predicate takes more than one argument (operator/2 with arg 1 lists each operator's name)."
                         }
                     },
                     "additionalProperties": false
@@ -917,9 +923,14 @@
                                 "type": "string",
                                 "minLength": 1
                             },
+                            "arg": {
+                                "type": "integer",
+                                "minimum": 1,
+                                "description": "A SWI-Prolog predicate's argument (1-based) whose solutions Kibi reads, when the predicate takes more than one argument (operator/2 with arg 1 lists each operator's name)."
+                            },
                             "source": {
                                 "type": "object",
-                                "description": "A project source Kibi reads by itself. reader json or yaml: {file, path?, select?: keys|values|items}. glob: {pattern, capture?, ignore?} (capture true reads what each * matched). openapi: {file, select?: operations|unsecured_operations|security_schemes|responses}. references: {files, extract: env|imports|calls|string_args|thrown|property, callee?, key?, ignore?}. schema: {format: drizzle|prisma|sql, file (drizzle, prisma) or files (sql migrations), exports?, table?, select?: tables|columns|required_columns|nullable_columns|foreign_keys}. routes: {file, export, framework?: hono|express, path_prefix?, names_from?, select?: routes|middleware}. validator: {file, export, select?: fields|required_fields|optional_fields}. Paths are repository-relative. A member Kibi cannot read statically fails the read with its location.",
+                                "description": "A project source Kibi reads by itself. reader json or yaml: {file, path?, select?: keys|values|items}. glob: {pattern, capture?, ignore?} (capture true reads what each * matched). openapi: {file, select?: operations|unsecured_operations|security_schemes|responses}. references: {files, extract: env|imports|calls|string_args|thrown|property, callee?, key?, ignore?} over TypeScript, JavaScript, Python and SWI-Prolog files. schema: {format: drizzle|prisma|sql, file (drizzle, prisma) or files (sql migrations), exports?, table?, select?: tables|columns|required_columns|nullable_columns|foreign_keys}. routes: {file, export, framework?: hono|express, path_prefix?, names_from?, select?: routes|middleware}. validator: {file, export, select?: fields|required_fields|optional_fields}. prolog: {file, functor: Name/Arity, arg?} reads one argument of every fact with that functor in a SWI-Prolog file (requires/1 in pack.pl), without running it. Paths are repository-relative. A member Kibi cannot read statically fails the read with its location.",
                                 "required": [
                                     "reader"
                                 ],
@@ -934,7 +945,8 @@
                                             "references",
                                             "schema",
                                             "routes",
-                                            "validator"
+                                            "validator",
+                                            "prolog"
                                         ]
                                     }
                                 },
@@ -1003,6 +1015,11 @@
                                     "export": {
                                         "type": "string",
                                         "minLength": 1
+                                    },
+                                    "arg": {
+                                        "type": "integer",
+                                        "minimum": 1,
+                                        "description": "A SWI-Prolog predicate's argument (1-based) whose solutions Kibi reads, when the predicate takes more than one argument (operator/2 with arg 1 lists each operator's name)."
                                     }
                                 },
                                 "additionalProperties": false
@@ -1015,7 +1032,7 @@
                                 "properties": {
                                     "source": {
                                         "type": "object",
-                                        "description": "A project source Kibi reads by itself. reader json or yaml: {file, path?, select?: keys|values|items}. glob: {pattern, capture?, ignore?} (capture true reads what each * matched). openapi: {file, select?: operations|unsecured_operations|security_schemes|responses}. references: {files, extract: env|imports|calls|string_args|thrown|property, callee?, key?, ignore?}. schema: {format: drizzle|prisma|sql, file (drizzle, prisma) or files (sql migrations), exports?, table?, select?: tables|columns|required_columns|nullable_columns|foreign_keys}. routes: {file, export, framework?: hono|express, path_prefix?, names_from?, select?: routes|middleware}. validator: {file, export, select?: fields|required_fields|optional_fields}. Paths are repository-relative. A member Kibi cannot read statically fails the read with its location.",
+                                        "description": "A project source Kibi reads by itself. reader json or yaml: {file, path?, select?: keys|values|items}. glob: {pattern, capture?, ignore?} (capture true reads what each * matched). openapi: {file, select?: operations|unsecured_operations|security_schemes|responses}. references: {files, extract: env|imports|calls|string_args|thrown|property, callee?, key?, ignore?} over TypeScript, JavaScript, Python and SWI-Prolog files. schema: {format: drizzle|prisma|sql, file (drizzle, prisma) or files (sql migrations), exports?, table?, select?: tables|columns|required_columns|nullable_columns|foreign_keys}. routes: {file, export, framework?: hono|express, path_prefix?, names_from?, select?: routes|middleware}. validator: {file, export, select?: fields|required_fields|optional_fields}. prolog: {file, functor: Name/Arity, arg?} reads one argument of every fact with that functor in a SWI-Prolog file (requires/1 in pack.pl), without running it. Paths are repository-relative. A member Kibi cannot read statically fails the read with its location.",
                                         "required": [
                                             "reader"
                                         ],
@@ -1030,7 +1047,8 @@
                                                     "references",
                                                     "schema",
                                                     "routes",
-                                                    "validator"
+                                                    "validator",
+                                                    "prolog"
                                                 ]
                                             }
                                         },
@@ -1055,6 +1073,11 @@
                         "export": {
                             "type": "string",
                             "minLength": 1
+                        },
+                        "arg": {
+                            "type": "integer",
+                            "minimum": 1,
+                            "description": "A SWI-Prolog predicate's argument (1-based) whose solutions Kibi reads, when the predicate takes more than one argument (operator/2 with arg 1 lists each operator's name)."
                         }
                     },
                     "additionalProperties": false,
@@ -1073,6 +1096,11 @@
                         "export": {
                             "type": "string",
                             "minLength": 1
+                        },
+                        "arg": {
+                            "type": "integer",
+                            "minimum": 1,
+                            "description": "A SWI-Prolog predicate's argument (1-based) whose solutions Kibi reads, when the predicate takes more than one argument (operator/2 with arg 1 lists each operator's name)."
                         }
                     },
                     "additionalProperties": false,

package/dist/traceability/analysis-gate.d.ts

@@ -32,7 +32,9 @@ type AnalysisObligation<Range extends LineRange> = Readonly<{
  * - A local gap (a macro, decorator or other declared limitation) matters only
  *   where it overlaps the changed lines; elsewhere the file was already in that
  *   state and this change did not touch it.
- * - Unsupported after-side analysis needs one whole-file review.
+ * - Unsupported after-side analysis needs one whole-file review, unless the
+ *   project lists the grammar plugin and only its kibi-lang pack is missing or
+ *   another version: that blocks, so a missing install never disarms the gate.
  */
 export declare function analysisObligation<Range extends LineRange>(side: "before" | "after", analysis: GateAnalysis<Range> | null | undefined, newHunkRanges: readonly HunkRange[]): AnalysisObligation<Range>;
 export {};

package/dist/traceability/analysis-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analysis-gate.d.ts","sourceRoot":"","sources":["../../src/traceability/analysis-gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAUjD,KAAK,SAAS,GAAG,QAAQ,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAGlE,MAAM,MAAM,YAAY,CAAC,KAAK,SAAS,SAAS,IAAI,QAAQ,CAAC;IAC3D,MAAM,EAAE,IAAI,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,CAAC;IACpD,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,eAAe,EAAE,SAAS,CAAC,KAAK,GAAG,QAAQ,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,EAAE,CAAC;CACpE,CAAC,CAAC;AAEH,gEAAgE;AAChE,KAAK,kBAAkB,CAAC,KAAK,SAAS,SAAS,IAC3C,QAAQ,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAC1B,QAAQ,CAAC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,QAAQ,CAAC;IAAE,IAAI,EAAE,oBAAoB,CAAA;CAAE,CAAC,GACxC,QAAQ,CAAC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAA;CAAE,CAAC,CAAC;AAuBnE;;;;;;;;;;;GAWG;AAEH,wBAAgB,kBAAkB,CAAC,KAAK,SAAS,SAAS,EACxD,IAAI,EAAE,QAAQ,GAAG,OAAO,EACxB,QAAQ,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,SAAS,EAChD,aAAa,EAAE,SAAS,SAAS,EAAE,GAClC,kBAAkB,CAAC,KAAK,CAAC,CAqB3B"}
+{"version":3,"file":"analysis-gate.d.ts","sourceRoot":"","sources":["../../src/traceability/analysis-gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAUjD,KAAK,SAAS,GAAG,QAAQ,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAGlE,MAAM,MAAM,YAAY,CAAC,KAAK,SAAS,SAAS,IAAI,QAAQ,CAAC;IAC3D,MAAM,EAAE,IAAI,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,CAAC;IACpD,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,eAAe,EAAE,SAAS,CAAC,KAAK,GAAG,QAAQ,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,EAAE,CAAC;CACpE,CAAC,CAAC;AAEH,gEAAgE;AAChE,KAAK,kBAAkB,CAAC,KAAK,SAAS,SAAS,IAC3C,QAAQ,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAC1B,QAAQ,CAAC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,QAAQ,CAAC;IAAE,IAAI,EAAE,oBAAoB,CAAA;CAAE,CAAC,GACxC,QAAQ,CAAC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAA;CAAE,CAAC,CAAC;AAuBnE;;;;;;;;;;;;;GAaG;AAEH,wBAAgB,kBAAkB,CAAC,KAAK,SAAS,SAAS,EACxD,IAAI,EAAE,QAAQ,GAAG,OAAO,EACxB,QAAQ,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,SAAS,EAChD,aAAa,EAAE,SAAS,SAAS,EAAE,GAClC,kBAAkB,CAAC,KAAK,CAAC,CAgC3B"}

package/dist/traceability/analysis-gate.js

@@ -24,7 +24,9 @@ function rangesTouchingHunks(ranges, hunks) {
  * - A local gap (a macro, decorator or other declared limitation) matters only
  *   where it overlaps the changed lines; elsewhere the file was already in that
  *   state and this change did not touch it.
- * - Unsupported after-side analysis needs one whole-file review.
+ * - Unsupported after-side analysis needs one whole-file review, unless the
+ *   project lists the grammar plugin and only its kibi-lang pack is missing or
+ *   another version: that blocks, so a missing install never disarms the gate.
  */
 // implements REQ-source-analysis-v2
 export function analysisObligation(side, analysis, newHunkRanges) {
@@ -32,6 +34,12 @@ export function analysisObligation(side, analysis, newHunkRanges) {
         return { kind: "none" };
     if (analysis.status === "failed")
         return { kind: "blocked", reason: "source analysis failed" };
+    if (analysis.status === "unsupported" &&
+        analysis.diagnosticCodes.some((code) => code.startsWith("TREESITTER_LANGUAGE_PACK_")))
+        return {
+            kind: "blocked",
+            reason: "the kibi-lang grammar pack for this file is not installed at the version kibi-plugin-treesitter pins; kibi doctor gives the install line",
+        };
     if (analysis.status === "unsupported")
         return { kind: "unsupported_review" };
     if (analysis.uncoveredRanges.length === 0)

package/dist/traceability/staged-file-coverage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staged-file-coverage.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-file-coverage.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,eAAO,MAAM,mCAAmC,EAC9C,8BAAuC,CAAC;AAE1C,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC7B,aAAa,EAAE,UAAU,CAAC,eAAe,CAAC,CAAC;IAC3C,WAAW,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC;IAClC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,CAAC,EAAE;QACf,MAAM,EAAE;YACN,MAAM,EAAE,MAAM,CAAC;YACf,QAAQ,EAAE,MAAM,CAAC;YACjB,WAAW,EAAE,MAAM,CAAC;YACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;YAC1B,gBAAgB,EAAE,MAAM,CAAC;YACzB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;SACpC,GAAG,IAAI,CAAC;QACT,KAAK,EAAE;YACL,MAAM,EAAE,MAAM,CAAC;YACf,QAAQ,EAAE,MAAM,CAAC;YACjB,WAAW,EAAE,MAAM,CAAC;YACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;YAC1B,gBAAgB,EAAE,MAAM,CAAC;YACzB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;SACpC,GAAG,IAAI,CAAC;KACV,CAAC;CACH;AAED,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,+BAA+B,GAAG,kCAAkC,CAAC;IACzE,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,KAAK,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,OAAO,mCAAmC,CAAC;IACpD,QAAQ,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC7E,KAAK,EAAE,wBAAwB,EAAE,CAAC;IAClC,WAAW,EAAE,4BAA4B,EAAE,CAAC;CAC7C;AAGD,KAAK,SAAS,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;AA+OrD,2FAA2F;AAC3F,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,UAAU,EAAE,EAChC,MAAM,GAAE,SAA4B,GACnC,wBAAwB,CA0G1B"}
+{"version":3,"file":"staged-file-coverage.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-file-coverage.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,eAAO,MAAM,mCAAmC,EAC9C,8BAAuC,CAAC;AAE1C,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC7B,aAAa,EAAE,UAAU,CAAC,eAAe,CAAC,CAAC;IAC3C,WAAW,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC;IAClC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,CAAC,EAAE;QACf,MAAM,EAAE;YACN,MAAM,EAAE,MAAM,CAAC;YACf,QAAQ,EAAE,MAAM,CAAC;YACjB,WAAW,EAAE,MAAM,CAAC;YACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;YAC1B,gBAAgB,EAAE,MAAM,CAAC;YACzB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;SACpC,GAAG,IAAI,CAAC;QACT,KAAK,EAAE;YACL,MAAM,EAAE,MAAM,CAAC;YACf,QAAQ,EAAE,MAAM,CAAC;YACjB,WAAW,EAAE,MAAM,CAAC;YACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;YAC1B,gBAAgB,EAAE,MAAM,CAAC;YACzB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;SACpC,GAAG,IAAI,CAAC;KACV,CAAC;CACH;AAED,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,+BAA+B,GAAG,kCAAkC,CAAC;IACzE,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,KAAK,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,OAAO,mCAAmC,CAAC;IACpD,QAAQ,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC7E,KAAK,EAAE,wBAAwB,EAAE,CAAC;IAClC,WAAW,EAAE,4BAA4B,EAAE,CAAC;CAC7C;AAGD,KAAK,SAAS,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;AAmPrD,2FAA2F;AAC3F,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,UAAU,EAAE,EAChC,MAAM,GAAE,SAA4B,GACnC,wBAAwB,CA6G1B"}

package/dist/traceability/staged-file-coverage.js

@@ -2,7 +2,7 @@ import { execFileSync } from "node:child_process";
 import { load as parseYaml } from "js-yaml";
 import { extractFromManifestString } from "../extractors/manifest.js";
 import { extractFromMarkdownString } from "../extractors/markdown.js";
-import { CANONICAL_ENTITY_PATHS, isEntityLanePath } from "../utils/kb-paths.js";
+import { CANONICAL_ENTITY_PATHS, KB_ROOT, isEntityLanePath, } from "../utils/kb-paths.js";
 export const STAGED_FILE_COVERAGE_RESULT_VERSION = "kibi.staged-file-coverage.v1";
 function defaultGitReader(args) {
     return execFileSync("git", args, {
@@ -136,6 +136,9 @@ function stagedManifestContent(inventory) {
         return undefined;
     return file.status === "D" ? null : (file.content ?? null);
 }
+function isKibiManagedPath(path) {
+    return path.replaceAll("\\", "/").startsWith(`${KB_ROOT}/`);
+}
 function sourcePaths(entry) {
     return new Set([entry.path, ...(entry.oldPath ? [entry.oldPath] : [])]);
 }
@@ -253,7 +256,9 @@ export function analyzeStagedFileCoverage(inventory, reader = defaultGitReader)
             evidencePaths,
             providerId: entry.analysisDepth === "symbol" ? "ts-morph" : null,
         });
-        if (entry.analysisDepth !== "file")
+        // Kibi writes everything under .kb/ (schema, manifest, entities); it is
+        // knowledge, not product code, so it needs no requirement ownership.
+        if (entry.analysisDepth !== "file" || isKibiManagedPath(entry.path))
             continue;
         if (requirementIds.length === 0) {
             diagnostics.push({

package/dist/traceability/symbol-extract.d.ts

@@ -45,5 +45,22 @@ export declare function extractSymbolsFromStagedFile(stagedFile: StagedFile, man
 export declare function extractSymbolsFromStagedFileAsync(stagedFile: StagedFile, manifestLookup: ManifestLookup | undefined, options: ExtractSymbolsOptions & Readonly<{
     registry?: import("../plugins/registry.js").CapabilityRegistry;
 }>): Promise<ExtractedSymbol[]>;
+type HunkLineRange = {
+    startLine: number;
+    endLine: number;
+};
+/**
+ * Whether a partial result still places its declarations: every gap is local
+ * (no parser, timeout or integrity finding) and no output cap hid symbols.
+ */
+export declare function partialAnalysisSymbolsUsable(analysis: {
+    status?: string;
+    diagnostics?: readonly {
+        code: string;
+    }[];
+    uncoveredRanges?: readonly (HunkLineRange & {
+        reason: string;
+    })[];
+}): boolean;
 export { isPrivateClassMember };
 //# sourceMappingURL=symbol-extract.d.ts.map