kibi-cursor 2.11.0 → 2.12.0

package/skills/kibi-provable-code/SKILL.md

@@ -0,0 +1,203 @@
+---
+id: kibi-provable-code
+name: kibi-provable-code
+description: "Use when writing, designing or refactoring code that implements a Kibi requirement (policies, limits, allow-lists, roles, state machines, routes, env and config reads, validators, error types), when a source proof or a value/domain read is refused because Kibi cannot read a name statically (a computed key, a dynamic import or require, eval, reflection, globals()[name], getattr with a computed name, $$var, a macro), or when deciding how to treat generated or vendored code. Covers design practices that make code easier to review, test and replace and that also let Kibi prove claims exactly, the line between a good refactor and a contortion for the tool, the accepted dynamic exceptions (plugins, serialization, registries), and generated code as a boundary."
+version: 1.0.0
+kibiCompatibility: ">=1.0.0"
+tags:
+  - kibi
+  - proof
+  - code-quality
+  - design
+  - agent-guidance
+resources:
+  - resources/provable-patterns.md
+---
+## Goal
+
+Write code a reviewer can check by reading it. Code that states its decisions
+once, names what it depends on, and keeps decisions apart from effects is
+easier to review, test, change and replace. The same properties let Kibi read
+the code exactly and prove claims about it. Provability is a side effect of
+good design here, never a reason to make the design worse.
+
+This skill is about the code. How to write the proof itself (proof kinds,
+`value_source`, `domains`, the `source` readers) is in
+`kibi-usage/resources/proof.md`; links between requirements, symbols and tests
+are in `kibi-traceability`.
+
+## Interface Selection
+
+Use the visible approved MCP tools or the trusted project-local CLI as equal
+peer interfaces (CLI JSON: `printf '%s\n' '{"query":"..."}' | npx --no-install
+kibi search --input -`). Exact routes are in
+`kibi-usage/resources/operation-access.md`. If neither is available, write the
+code by the practices below and say that Kibi could not be consulted. Never
+read or edit `.kb/` files directly.
+
+## Before you design
+
+1. `kb_search` the area (or its `sourceLocations`) and `kb_query({id})` the
+   requirements the code implements, with `includeBody: true` when you need
+   their prose. A claim names the decision the code has to state: a limit, a
+   set of allowed values, a transition, a forbidden dependency.
+2. Shape the code so that decision sits in one readable place (see
+   Practices). The requirement tells you what to make explicit; it never
+   tells you to bend the design.
+3. After the change, `kb_check` and `kb_status` show whether links and
+   proof receipts went stale. Re-prove what the change touched.
+
+## The test for every change
+
+Before changing code so that Kibi can read it, ask: would a reviewer who has
+never heard of Kibi accept this change on its own merits? Keep the change
+only if the answer is yes, because it removes duplication, names a hidden
+dependency, narrows a module, or makes a decision testable.
+
+Never do any of these to satisfy Kibi:
+
+- Duplicate a value into a second constant, or add an export that only the
+  proof reads, when the code already has one source of truth. A count claim
+  reads the size of the list; a dotted export (`POLICY.limit`) reads a field.
+- Unroll a loop, inline a lookup table, or replace a clear generic mechanism
+  with copy-pasted branches so that a reader sees literal names.
+- Split a cohesive function or module only to shrink a proof's file list.
+- Drop a file from a proof's `files`, rename it, or mark hand-written code as
+  generated, so that a refused read goes away.
+- Weaken types, add casts or silence a linter so that a construct parses as
+  a literal.
+
+When good design and a readable proof disagree, keep the good design and
+change the evidence instead: model a claim the code can show, or keep the
+requirement at `tested` with ordinary tests. `tested` is a sound evidence
+level. `proved` is worth reaching only where the code is already shaped well.
+
+## Practices
+
+Each practice below is a general one. Kibi's benefit is listed second.
+
+1. **State each decision once, as data.** Limits, allow-lists, role-to-
+   permission tables, supported formats, transition tables and feature lists
+   belong in one named constant that the behaviour reads, not in conditions
+   repeated across files. One place to change, one place to review.
+   Kibi reads the constant directly (`value_source`, `exhaustive`,
+   `state_machine`, `regex`, a `domains` export).
+2. **Name dependencies where they are used.** Import modules by literal
+   specifiers, read environment variables and configuration keys by literal
+   names, and call functions by name. A reader, an IDE and a bundler can then
+   find every use. Kibi's `references` reader lists them exactly
+   (`imports`, `env`, `calls`, `string_args`, `property`).
+3. **Read configuration at one boundary.** Read the environment and config
+   files in one module that turns them into a typed object, and pass that
+   object on. The rest of the code is then testable without a real
+   environment, and the full list of settings sits in one file. Kibi proves
+   "the service reads only these variables" over that one file.
+4. **Keep decisions pure and effects at the edge.** A function that decides
+   (`canInvite(role, target)`, `nextState(state, event)`, `priceFor(plan)`)
+   takes its inputs as arguments and returns a value; the code around it does
+   the I/O. Pure deciders are unit-testable over every input. Kibi's `rule`
+   and `state_machine` kinds call them on every combination of a finite
+   domain and prove the claim for all of them.
+5. **Make states and their transitions explicit.** Prefer one status field
+   with a transition table (or a `next(state, event)` function) over several
+   booleans that together imply a state. Impossible combinations disappear,
+   and Kibi can prove reachability and "can never become" claims.
+6. **Name failures.** Throw or return named error types (`ForbiddenError`,
+   `ErrQuotaExceeded`) instead of bare strings or a generic error with a
+   computed message. Callers can handle them precisely, and Kibi's `thrown`
+   read lists them.
+7. **Declare routes, middleware and schemas in one place.** Register routes in
+   a router module, declare middleware on the route or the mount, and derive
+   types from one schema or validator instead of keeping parallel
+   definitions. Kibi's `routes`, `schema` and `validator` readers read them.
+8. **Keep modules small and single-purpose.** A module with one reason to
+   change is easier to replace. A proof over it covers fewer files, so its
+   receipt stales only when that concern changes.
+
+`resources/provable-patterns.md` has before-and-after examples per language.
+
+## Dynamic code
+
+Runtime lookups and code built from text hide what a program does from
+every static reader, people included: `eval`, `new Function`, `exec`,
+`globals()[name]`, `getattr(obj, name)` with a computed name, PHP `$$var` and
+`$obj->$method()`, a dynamic `import()` or `require(path)` with a computed
+path, reflection (`Class.forName`, `Method.invoke`, `reflect.Value.Call`,
+`Type.GetMethod`), C# `dynamic`, `process.env[key]` with a computed key, and
+C# `#if` around the code a claim is about. Kibi refuses a read that meets
+one of these and names the line. Rust `#[cfg]` items are read as if every
+build compiled them, so a "never" claim holds in each build; a `cfg_attr`
+Kibi cannot split is still refused.
+
+Replace a dynamic lookup when an explicit form is clearer, which is the usual
+case: a computed `getattr` dispatch becomes a dict from name to function, a
+computed env key becomes a named setting in the config module, `$$var`
+becomes an array, a computed `require` becomes a static map of loaders.
+
+Keep the dynamic form where it is the design:
+
+- **Plugins and extension points**, where the set of implementations is open
+  by design.
+- **Serialization and ORMs**, which map names to fields by reflection.
+- **Registries and dependency injection**, which wire implementations by key.
+- **Generated code** (next section).
+
+For these, keep the dynamic part small and in one place: one loader or
+registry module, with the code around it written statically. List the known
+entries in a literal table where one exists (a registry of built-in handlers),
+so the rest stays readable. Then model claims that do not depend on the open
+part, or keep them at `tested`. Never write a proof that pretends an open set
+is closed.
+
+## Generated code
+
+Treat generated code as a boundary: it is the generator's output, not code the
+project writes, so it does not have to follow these practices and is not
+refactored to make Kibi read it.
+
+1. **Do not hand-edit it.** Change the input (schema, grammar, OpenAPI or
+   protobuf spec, template) and regenerate. A hand edit is lost on the next
+   run and hides the real source of the behaviour.
+2. **Mark it.** Keep the generator's header (`// Code generated ... DO NOT
+   EDIT.`, `@generated`, `auto-generated`) and list generated paths as
+   `linguist-generated` (vendored code as `linguist-vendored`) in
+   `.gitattributes`. `kibi doctor` and `kibi init` then leave those files out
+   of language pack suggestions unless the KB names them.
+3. **Put requirements on the input.** A claim about what the generated code
+   exposes is a claim about the generator input: prove it over the schema,
+   spec or grammar with the `json`/`yaml`/`openapi`/`schema`/`validator`
+   readers, or over the generator's configuration.
+4. **Keep the hand-written wrapper thin and readable.** The adapter that
+   calls generated code is ordinary code and follows the practices above;
+   link it with `implements` and prove claims over it.
+5. **Use tests where the output itself matters.** When a requirement depends
+   on what the generator produced (a parser accepts this input, a client
+   sends this header), cover it with a test or a snapshot, and check in CI
+   that regenerating gives the committed files. That evidence is `tested`.
+   Prefer the input over the generated files for a source proof: generated
+   code often uses constructs the readers refuse, and a proof over generated
+   text stales on every regeneration and follows the generator's version
+   rather than the requirement.
+6. **Do not link generated symbols as the implementation** of a requirement
+   when a hand-written wrapper or the generator input says the same thing.
+
+## When a read is refused
+
+1. Read the refusal: it names the file, the line and the construct.
+2. If the construct is incidental (a computed key that is really one of three
+   literal names), rewrite it the explicit way, run the tests, and retry.
+3. If it is one of the accepted exceptions, leave it. Narrow the claim to the
+   files that are static, or model a claim the code can show, and keep the
+   rest at `tested`. Keep every file the claim is about in `files`.
+4. If the file is generated, move the claim to the generator input.
+5. Report what you changed and why it improves the code, and which claims
+   stayed `tested` and why.
+
+## Typed results
+
+Parse `kibiProtocol`, `status`, diagnostics and typed `nextActions` on every
+Kibi result. A refused proof read names the file, line and construct; it is
+never an empty member list, so never read it as "nothing found". On
+`committed_with_repairs` a write stands: run the repair actions and never
+resend the original. Kibi authors tracked files but never Git-stages or
+commits them.

package/skills/kibi-provable-code/resources/provable-patterns.md

@@ -0,0 +1,172 @@
+# Provable Patterns
+
+Before-and-after examples for the practices in `kibi-provable-code`. Each
+"after" is a change worth making without Kibi; the note says what Kibi can
+then read. Keep the "before" when the dynamic form is the design (plugins,
+serialization, registries, generated code).
+
+## One source of truth for a decision
+
+```ts
+// Before: the limit lives in two conditions.
+if (files.length > 20) throw new Error("too many files");
+// ...elsewhere
+const remaining = 20 - files.length;
+
+// After: one named constant that both read.
+export const UPLOAD_POLICY = { maxFiles: 20 } as const;
+if (files.length > UPLOAD_POLICY.maxFiles) throw new TooManyFilesError();
+```
+
+Kibi reads `UPLOAD_POLICY.maxFiles` as a `value_source` with a dotted export.
+Do not add a second `MAX_FILES` export just for the proof.
+
+```py
+# Before: allowed roles spread over checks.
+if role == "owner" or role == "admin": ...
+
+# After: one set, read by the check.
+INVITER_ROLES = frozenset({"owner", "admin"})
+if role in INVITER_ROLES: ...
+```
+
+## Dispatch through a table, not a computed name
+
+```py
+# Before: any attribute name can be called.
+handler = getattr(self, f"handle_{event.kind}")
+# or: globals()[f"handle_{event.kind}"]
+
+# After: the handled kinds are listed.
+HANDLERS = {"created": handle_created, "deleted": handle_deleted}
+handler = HANDLERS[event.kind]
+```
+
+```php
+// Before
+$$name = $value;          // variable variables
+$this->$method($arg);     // computed method name
+
+// After
+$settings[$name] = $value;
+match ($method) { 'archive' => $this->archive($arg), 'restore' => $this->restore($arg) };
+```
+
+```ts
+// Before: the loaded module depends on run-time text.
+const exporter = await import(`./exporters/${format}.js`);
+
+// After: the supported formats are a literal map.
+const EXPORTERS = {
+  csv: () => import("./exporters/csv.js"),
+  pdf: () => import("./exporters/pdf.js"),
+} as const;
+const exporter = await EXPORTERS[format]();
+```
+
+The table is also the list of supported values: Kibi's `exhaustive` kind or
+an `Object.keys(EXPORTERS)` domain proves "only CSV and PDF are supported".
+
+## Configuration at one boundary
+
+```ts
+// Before: environment reads spread through the code, some computed.
+const url = process.env[`${service.toUpperCase()}_URL`];
+
+// After: config.ts reads every variable by name and exports a typed object.
+export const config = {
+  billingUrl: process.env.BILLING_URL,
+  searchUrl: process.env.SEARCH_URL,
+};
+```
+
+```go
+// After: one function reads the environment; the rest receives Config.
+func LoadConfig() Config {
+	return Config{Port: os.Getenv("PORT"), DatabaseURL: os.Getenv("DATABASE_URL")}
+}
+```
+
+`extract: env` over `config.ts` (or the Go file) proves "the service reads
+only these variables". Code elsewhere that reads the environment directly is
+then a review finding in its own right.
+
+## Pure deciders, effects at the edge
+
+```ts
+// Before: the decision reads the database and the session itself.
+async function invite(req) {
+  const me = await db.members.find(req.user);
+  if (me.role !== "owner" && !(me.role === "admin" && req.body.role !== "owner")) throw ...
+  await db.invites.insert(...);
+}
+
+// After: the decision is a pure function over finite inputs.
+export function canInvite(inviter: Role, invitee: Role): boolean {
+  return inviter === "owner" || (inviter === "admin" && invitee !== "owner");
+}
+async function invite(req) {
+  const me = await db.members.find(req.user);
+  if (!canInvite(me.role, req.body.role)) throw new ForbiddenError();
+  await db.invites.insert(...);
+}
+```
+
+Kibi's `rule` kind calls `canInvite` on every pair of roles.
+
+## Explicit state
+
+```ts
+// Before: several flags imply a state, and impossible pairs are possible.
+{ sent: true, paid: false, cancelled: true }
+
+// After: one status and its transitions.
+export const INVOICE_TRANSITIONS = {
+  draft: ["sent", "cancelled"],
+  sent: ["paid", "cancelled"],
+  paid: [],
+  cancelled: [],
+} as const;
+```
+
+`state_machine` proves "a cancelled invoice can never become paid".
+
+## Named failures
+
+```java
+// Before
+throw new RuntimeException("quota " + kind + " exceeded");
+// After
+throw new QuotaExceededException(kind);
+```
+
+The `thrown` read lists `QuotaExceededException`; callers catch it by type.
+
+## Accepted dynamic code
+
+Keep reflection, open registries and dynamic loading where they are the
+design, and fence them:
+
+- One loader module discovers plugins; the rest of the code calls the
+  plugin interface statically.
+- An ORM or serializer maps fields by reflection; claims about the fields
+  are proved over the schema or validator, not over the mapper.
+- A dependency-injection container wires by key; the bindings sit in one
+  module with literal keys where the container allows it.
+- Built-in entries of an open registry live in a literal table, so a claim
+  about the built-ins is provable while the open part stays `tested`.
+
+## Generated and vendored code
+
+- Keep the generator header and list the paths in `.gitattributes`:
+
+  ```gitattributes
+  src/gen/** linguist-generated
+  third_party/** linguist-vendored
+  ```
+
+- Change the generator input and regenerate; never hand-edit the output.
+- Prove claims over the input (`openapi`, `schema`, `json`/`yaml`,
+  `validator` readers) and over the thin hand-written wrapper.
+- Cover behaviour of the output with tests or snapshots, plus a CI step
+  that regenerates and fails on a diff.

package/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.40.1
+version: 2.42.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -456,6 +456,9 @@ arithmetic, smt, rule, state_machine, regex, source) reach `proved` for the clai
 predicate bound with `harness_for` (scope `harness`) also counts toward
 `proved`; an intent-scope binding stays `tested`. When the `evidence-floor` rule fails, follow Debugging
 proof regressions in `resources/proof.md` and use `kibi proof explain`.
+Load `kibi-provable-code` before writing or refactoring code that implements
+a requirement, when a source read is refused for a computed name, dynamic
+import, reflection or eval, or when deciding how to treat generated code.
 
 ## Quantified claims: model the dimension
 

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

@@ -263,7 +263,8 @@ left:
   `openapi` (`file`, `select: operations|unsecured_operations|...`),
   `references` (`files`, `extract: env|imports|calls|string_args|thrown|
   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:
+  Java, C#, Rust, PHP, C, Bash and Terraform/HCL 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:
@@ -292,9 +293,11 @@ 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
+- `references` over Go, Java, C#, Rust, PHP, C, Bash or Terraform/HCL
+  needs `kibi-plugin-treesitter` and the language's grammar pack
+  (`kibi-lang-go`, `kibi-lang-java`, `kibi-lang-csharp`, `kibi-lang-rust`,
+  `kibi-lang-php`, `kibi-lang-c`, `kibi-lang-bash`, `kibi-lang-hcl`) 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
@@ -304,12 +307,30 @@ left:
   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
+  `*.name`. Rust `#[cfg(...)]` items are read as if every build compiled
+  them (`#[cfg(test)]` items are skipped): a name two gated `use` items
+  bind is listed under both, and a `cfg_attr` counts as the attributes it
+  applies, so `excludes` holds in every build while `includes` and `eq`
+  may count a member only some builds compile. Reflection, a name
+  computed at run time, the whole environment, C# `dynamic` and `#if`, a
+  `cfg_attr` Kibi cannot split, 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). PHP class names are written in full with
+  backslashes (`App\Mail\Mailer::send`) and functions in lower case;
+  PHP names ignore letter case, so a PHP `excludes` refuses a member that
+  differs from an item only in case (`Exec` for `exec`);
+  Terraform/HCL reads only `property`; C and Bash have no `thrown`, and
+  Bash no `property`. A Bash variable the script expands but never sets is
+  an environment read, and one it sets only on some paths is refused. A
+  Terraform `override.tf`, `*_override.tf` or `.tofu` file in the folder
+  refuses an HCL read, so a value claim there cannot be proved. C
+  `property` reads only initializers (a later `cfg.field = v` is not
+  seen), Bash does not read code handed to another interpreter
+  (`python -c`, `awk`), and the commands a sourced Bash file or an
+  included C file runs are that file's: model such claims over the code
+  that holds them, listing every file it runs.
+  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.