kibi-cursor 2.9.3 → 2.9.6

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "2.9.3",
+  "version": "2.9.6",
   "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,101 @@
 # kibi-cursor
 
+## 2.9.6
+
+### Patch Changes
+
+- 90e1657: Source proofs no longer prove false claims about module paths, routes and file captures, and they read real projects' schemas, validators and middleware.
+
+  Fixed, where a false claim could be proved:
+  - Set fact members that contain a slash (`rxjs/operators`, `node:fs/promises`, `GET /api/users`, `finance/de`) were cut to their last path segment before Kibi compared them, so "the app must never import rxjs/operators" could prove while the app imported it. Members are now compared whole.
+  - The environment extractor now reads through `as`, `<T>` and `satisfies` casts, so `(import.meta as X).env.FOO` is read and an environment object (or `import.meta` itself) handed to a variable fails the read instead of hiding later reads.
+  - A glob that matches no file, and SQL migrations with no `CREATE TABLE`, now fail the read, so a mistyped pattern cannot decide a `subset_of` or `excludes` fact over an empty set.
+  - A `required_fields` or `nullable_fields` fact with `subset_of` or `excludes` is refused with a reason instead of being compared with whatever members the contract selected.
+
+  Readers:
+  - The SQL migration replay reads quoted and schema-qualified names (`"public"."messages"`), several actions per `ALTER TABLE`, `ADD PRIMARY KEY` and `DROP CONSTRAINT` of a foreign key, keeps `$$` function bodies whole, and skips actions that change no column, nullability or foreign key (row level security, triggers, ownership, defaults, column types). Supabase migration folders now read.
+  - The validator reader reads valibot objects, and any field that is a Standard Schema.
+  - `names_from` names middleware that a zero-argument factory export makes (`requireAuthentication()`) after the factory.
+  - The `thrown` extractor reads `throw createX()` as `createX`.
+  - A glob `capture` with `**` reads `finance/de` instead of `finance/de/`.
+  - A source read's dependencies follow tsconfig `extends` and workspace packages linked into `node_modules`, so a change in a sibling package stales the receipt.
+  - A claim a source proof derives is bound with the new scope `source`.
+
+  Modeling:
+  - "Every X must have Y" becomes a `required_fields` fact only when the sentence names a schema (a table, object, model and similar, or the words field, column or property), so "Every organization must have an owner" stays a behavioural claim.
+  - "A member can never become owner" models `member->owner` (the article was read as the state), and the machine may go unnamed.
+  - Scoped package names (`@supabase/supabase-js`), "must be exactly A and B" sets and "at least 30 routes under /api/orgs" counts are recognised.
+  - `kb_model` in requirement mode accepts the `includes`, `subset_of`, `excludes` and `matches` operators and a list `value` for set facts.
+
+  The kibi-usage skill (2.32.0) and the proof guide describe the reader details, the empty-read rule and the minimum kibi-cli for the certificate builders.
+
+## 2.9.5
+
+### Patch Changes
+
+- c118085: Formal proofs now reach the claims real services make about their routes, database schemas, configuration and code. A new `source` certificate proof kind lets Kibi read a project source itself and check a set fact against what it read, so the test only has to run:
+  - `json` and `yaml` read keys, values or items at a path; `glob` reads matching files (or what each `*` matched); `openapi` reads operations, unsecured operations, security schemes or responses.
+  - `references` reads environment variables, imports, calls, string arguments, thrown errors or property accesses from TypeScript, JavaScript and Python files. A member Kibi cannot read statically, such as a computed environment variable name, fails the read with its location instead of leaving it out.
+  - `schema` reads tables, columns, required or nullable columns and foreign keys from Drizzle, Prisma or SQL migrations.
+  - `routes` reads a Hono or Express app's routes and the middleware each route runs, including mounted routers.
+  - `validator` reads a zod or pydantic schema's fields, required fields or optional fields.
+
+  A receipt for a source proof goes stale when any file the read touched changes.
+
+  Set facts gain the `subset_of` ("must be one of") and `excludes` ("must never use") operators alongside `eq` and `includes`. Field claims (`required_fields`, `nullable_fields`) accept `table.field` members, and a `middleware` fact with `includes` requires every matching route to run the listed middleware.
+
+  State machine proofs decide temporal claims: a `reachable_pairs` fact with `excludes` ("a cancelled invoice can never become paid") and a `required_waypoints` fact ("every path from draft to paid must pass through approved"). Every machine projection accepts the four set operators.
+
+  A `rule` contract can take a domain from a project source, and a predicate with `harness_for: [SYM-...]` proves its claim at the new `harness` scope when the predicate is a test harness that drives real code. `value_source` accepts `{source, measure: count}`.
+
+  The semantic advisor and `kibi model` turn these sentence shapes into the matching facts. `kibi-cli/proof-certificates` adds `sourceCertificate` and `readProjectSource`.
+
+  The kibi-usage skill (2.31.0) explains the new kind and operators. kibi-traceability (2.3.0) lists every certificate kind that reaches proved and the code or harness scope it needs, kibi-freshness (2.3.0) says a changed file a source proof read also leaves its receipt pending re-proof, and kibi-decisions (1.4.0) says a firm rule a certificate kind can check is proved by a certificate test.
+
+## 2.9.4
+
+### Patch Changes
+
+- 4d55860: Claim-bound proofs are easier to adopt on an existing project.
+  - A count claim over a collection reads the collection itself: a `value_source` entry with `measure: count` uses the size of a list, set, map or object export, so "exactly 32 tools" no longer needs a number export added beside the list just for the proof.
+  - `kibi migrate`'s claim-binding reviews now list every modeled claim the test reaches through its scenarios, with the binding a certificate of its kind would get (provable, attested only, or why the kind cannot express the fact), instead of an empty list when no claim was provable as modeled.
+  - The semantic advisor models "every member of S has P" requirements as a set fact named for P whose value is S, so the property stays in the requirement instead of only in the test.
+
+  Deleting an `implements` relationship now also removes the target from a symbol's legacy `links:` list in `symbols.yaml` (dropping the list when it empties), so the deleted edge no longer comes back on the next `kibi sync --rebuild`.
+
+  The kibi-usage skill (2.28.0) explains count measures and every-member claims.
+
+- 42566ee: Formal proofs now reach claims that are not numbers. Three new certificate proof kinds read their model from the code and decide the claim exactly:
+  - `rule`: Kibi calls the code's predicate functions (`predicate_source`) on every combination of the finite domains the code exports (`domains`) and model checks the claim's fact against that table. A `kibi.logic.v1` rule must hold for every assignment of its variables, a predicate fact (including decision predicates such as `permission_rule`) must be decided as it says, and a set fact whose property names a predicate needs it to hold for every member. A failure names the assignment that breaks the rule.
+  - `state_machine`: Kibi reads a transition table or a `next(state, event)` function and checks the transitions, states, initial, terminal or reachable states a set fact names, exactly. Rules over a machine can use `transition`, `reachable`, `initial`, `terminal` and `state`.
+  - `regex`: Kibi decides whether the code's pattern (a JavaScript `RegExp` or a Python `re.compile`) accepts exactly the strings a fact's pattern describes, with each engine's own semantics for anchors, `.`, `\d` and case folding, and reports the shortest string only one side accepts. Patterns outside the regular subset (backreferences, lookaround, word boundaries and similar) are refused with the reason. A string constant is checked against an exact string fact the same way.
+
+  String facts gain the `matches` operator, and the semantic advisor models "X must match `re`", "X must be `value`" and "X transitions must be one of a -> b, ..." (and terminal, initial or reachable states) as facts these kinds prove. A `typecheck` proof of a set fact with `property_key: required_fields` checks that every member is a required, non-nullable field of the domain type. `kibi-cli/proof-certificates` adds `ruleCertificate`, `stateMachineCertificate`, `regexCertificate` and `failedCalls`.
+
+  The kibi-usage skill (2.29.0) explains the new kinds.
+
+- 4f06fd5: The kibi-usage skill (2.27.1) now links the full proof reference to its published page, https://looted.github.io/kibi/reference/proving.html, instead of a repository path that does not exist in the projects using Kibi.
+- 03197d8: The kibi-usage skill (2.29.3) lists all seven certificate proof kinds (`exhaustive`, `typecheck`, `arithmetic`, `smt`, `rule`, `state_machine` and `regex`) where it explains which tests reach `proved`.
+- c99f89b: Fixes for the certificate proof kinds and for running Kibi from inside a repository:
+  - `kibi` run from a subdirectory of a Kibi workspace now uses the workspace's knowledge base (the nearest enclosing `.kb/manifest.json`), the way git finds its repository. Before, it compiled a second, empty branch store in the subdirectory, so queries returned nothing and `kibi prove` reported no proof integration. Relative `--input`, `--output`, `--certificates` and `--write-certificates` paths still resolve from where the command was typed. `kibi init` and an explicit `KIBI_WORKSPACE` keep the current directory.
+  - A receipt whose certificate re-checks but derives none of the claims it names now records `evidence_level: tested`, the level coverage reports, instead of `proved`. The same holds for the `kibi prove` result rows.
+  - Kibi compiles typecheck witnesses with the import resolution of the nearest `tsconfig.json` (`module`, `moduleResolution`, `paths` and similar), while the checking options stay fixed and strict. A project that resolves like a bundler no longer needs `.js` extensions in witness imports.
+  - TypeScript is loaded from the package nearest the witness first. TypeScript 7, which ships without the compiler API, is skipped for an older install further up, and named in the rejection when there is none ("add typescript@6 as a dev dependency"), instead of being reported as missing.
+  - A rejected `required_fields` claim names each field that breaks it ("deletedAt is optional or nullable", "x is not a field"), also when the test's own witness failed to compile.
+  - A rejected arithmetic certificate, including a `measure: count` claim, names a value that satisfies the assumptions and breaks the claim ("count = 5 satisfies them and breaks it").
+  - The typecheck exhaustiveness check reads the witness's syntax tree: a `never` type or a `satisfies` map counts, the word "never" in a comment does not. It now applies only to contracts without `proves`; with `proves`, Kibi checks each claim with its own witness.
+  - Set facts gain the `includes` operator for "every member of the set has the property" claims, which the semantic advisor now proposes. Two `includes` facts on the same property never contradict, and one contradicts an `eq` set only when it names a member the `eq` set leaves out. Before, "every role in owner and admin can invite" and "every role in owner, admin and member can invite" were refused as a value conflict. The KB consistency certificates model `includes` as containment.
+
+  The kibi-usage skill (2.29.1) describes the `includes` operator and the typecheck changes.
+
+- bcbeebe: Follow-up fixes for the certificate proof kinds:
+  - A `rule` certificate now derives an `includes` set fact ("every role in owner and admin can invite"), checking the property on each listed member, so a true every-member claim reaches `proved`. Before, an `includes` fact was never read as a set and every binding to it was only attested. A `typecheck` certificate derives an `includes` fact on `required_fields`; the kinds that compare the whole set (`exhaustive`, a set-equality `typecheck`, `state_machine`) reject one, since they would read "at least these" as "exactly these".
+  - An arithmetic certificate whose assumptions contradict each other, such as a code count of 5 against a fact of exactly 4, is rejected with both values ("the assumptions contradict each other (count = 4 and count = 5) ...") instead of "the claim holds vacuously".
+  - A typecheck certificate whose own compile failed is rejected with the first error Kibi's compile of the witness reports, or with a note that Kibi's compile accepts it, instead of only "the type checker did not accept the witness". The declaration files the nearest `tsconfig.json` includes (a `reset.d.ts`, for example) are now part of the witness program.
+  - A receipt whose only derived claims are intent-scope (derived from the knowledge base's facts, with no value read from the code) records `evidence_level: tested`, the level coverage reports, instead of `proved`.
+
+  The kibi-usage skill (2.29.2) describes these and how to wire a count claim.
+
 ## 2.9.3
 
 ### Patch Changes

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.9.3",
+  "version": "2.9.6",
   "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-commit-review/SKILL.md

@@ -1,8 +1,8 @@
 ---
 id: kibi-commit-review
 name: kibi-commit-review
-description: "Use when kibi check --staged or the Kibi pre-commit hook blocks a commit (kibi_impact_evidence_missing, symbols_manifest_stale, symbol_granularity_violation, symbol-coverage, kibi check-generated drift, Staged impact review failed), or when preparing a commit or pull-request impact review. Covers reading the per-file Detail lines, authoring .kb/symbols.yaml symbol entries through kb_upsert, kibi sync --refresh-symbol-coordinates, staging the tracked Kibi evidence with git add, kb_prepare_impact_review for a staged or diff scope, the kibi signoff requirements summary to show before a commit, and how merge commits and migration renames are judged."
-version: 1.2.2
+description: "Use when kibi check --staged or the Kibi pre-commit hook blocks a commit (kibi_impact_evidence_missing, symbols_manifest_stale, symbol_granularity_violation, symbol-coverage, kibi check-generated drift, Staged impact review failed), or when preparing a commit or pull-request impact review. Covers reading the per-file Detail lines, authoring .kb/symbols.yaml symbol entries through kb_upsert, staging the tracked Kibi evidence with git add (symbol coordinates are derived and never staged), kb_prepare_impact_review for a staged or diff scope, the kibi signoff requirements summary to show before a commit, and how merge commits and migration renames are judged."
+version: 1.3.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -55,17 +55,17 @@ Never read or open any file under `.kb`, not even read-only with a file tool to
    - New or uncovered symbols: author a `symbol` entity per listed symbol
      through `kb_upsert` (`title` = the member the extractor names,
      `sourceFile`, `status: active`, `symbol_role: behavioral`, `implements`
-     to the requirement, `covered_by` to the test). Then run
-     `kibi sync --refresh-symbol-coordinates`.
-   - Only coordinates moved: `kibi sync --refresh-symbol-coordinates`.
+     to the requirement, `covered_by` to the test).
+   - Only lines moved: nothing to do. Symbol coordinates are derived locally
+     by every sync and never committed.
    - No behavior change (a genuine false positive): see the audited
      no-impact note in `resources/staged-gate.md`; it never covers a real
      behavior change.
 4. **Stage the evidence.** Kibi authors tracked files but never Git-stages or
    commits them. `git status --short .kb` lists what it wrote; `git add` the
-   entity Markdown, `.kb/relationships/` shards, `.kb/symbols.yaml` and
-   `.kb/symbol-coordinates.yaml` that belong to this change (use `git add -p`
-   when the files hold unrelated edits).
+   entity Markdown, `.kb/relationships/` shards and `.kb/symbols.yaml` that
+   belong to this change (use `git add -p` when the files hold unrelated
+   edits). `.kb/symbol-coordinates.yaml` is gitignored; never stage it.
 5. **Re-run** `kibi check --staged` (and `kibi check-generated --staged` when it
    failed) until it passes. Never bypass the hook (`--no-verify`) unless the
    person says so.

package/agent-plugin/skills/kibi-commit-review/resources/staged-gate.md

@@ -8,10 +8,10 @@ not the working tree, so a fix counts only once it is staged.
 ## Reading a finding
 
 ```text
-symbols_manifest_stale: .kb/symbol-coordinates.yaml is stale or missing for staged source files: src/billing/refund.ts
+symbols_manifest_stale: .kb/symbols.yaml does not cover the declarations of staged source files: src/billing/refund.ts
   Detail: src/billing/refund.ts — extraction finds 4 symbol(s), evidence covers 3.
       Not in .kb/symbols.yaml: approveRefund (line 42)
-  Suggestion: Author .kb/symbols.yaml entries for the uncovered symbols (kibi upsert, with implements/covered_by links), then run kibi sync --refresh-symbol-coordinates && git add .kb/symbol-coordinates.yaml .kb/symbols.yaml, then re-run kibi check --staged.
+  Suggestion: Author .kb/symbols.yaml entries for the uncovered symbols (kibi upsert, with implements/covered_by links). Stage .kb/symbols.yaml with the behavior edit, then re-run kibi check --staged.
 ```
 
 - Detail lines name every symbol, never a shortened list. `Evidence without a
@@ -24,15 +24,15 @@ symbols_manifest_stale: .kb/symbol-coordinates.yaml is stale or missing for stag
 
 | Id or message | Cause | Fix |
 | --- | --- | --- |
-| `kibi_impact_evidence_missing` | A staged behavior edit (changed lines in exported or behavior-bearing code, not comments or formatting) has no staged Kibi evidence. Test-only edits do not need it unless they add executable test symbols. | Query the owning knowledge; update it when behavior changed; stage entity Markdown under `.kb/`, authored `.kb/symbols.yaml` entries for the listed symbols, or refreshed `.kb/symbol-coordinates.yaml`. |
-| `symbols_manifest_stale` | Extraction output changed and the staged coordinates (or manifest) do not match it. | Author entries for the listed symbols first, then `kibi sync --refresh-symbol-coordinates`, then stage both manifests. |
+| `kibi_impact_evidence_missing` | A staged behavior edit (changed lines in exported or behavior-bearing code, not comments or formatting) has no staged Kibi evidence. Test-only edits do not need it unless they add executable test symbols. | Query the owning knowledge; update it when behavior changed; stage entity Markdown under `.kb/` or authored `.kb/symbols.yaml` entries for the listed symbols. A file whose every declaration already has a `.kb/symbols.yaml` entry needs nothing more. |
+| `symbols_manifest_stale` | A staged behavior file declares symbols `.kb/symbols.yaml` has no entry for, or an entry names a declaration that is gone. | Author entries for the listed symbols, re-point or retire entries whose declaration is gone, and stage `.kb/symbols.yaml`. Coordinates are derived locally and never staged. |
 | `symbol_granularity_violation` | A changed behavioral member is owned only by a coarse class or module symbol while a narrower declaration exists. | Add a symbol for the member itself (`title` = `Class.method` or the exported function) with its own links; use `granularity_reason` (`config-artifact`, `module-level-behavior`, `extractor-miss`, `legacy-link`, `test-suite`) only when it is true. |
 | `symbol-coverage` | A changed symbol, or a symbol whose staged manifest entry changed, fails the full-check rule on the staged knowledge. | The symbol `implements` the requirement and is `covered_by` a test that verifies it: through the requirement's scenario (`verified_by` scenario -> test) when it has one, else `verified_by` requirement -> test. A direct requirement -> test link does not count while a scenario exists. The finding's suggestion names the missing link (see `kibi-traceability`). |
 | `kibi_impact_override_missing_rationale` | A `Kibi-Impact: none` declaration has no `Rationale:` line. | Add the rationale, or drop the declaration and stage real evidence. |
 | `entity-context-missing` (staged entity) | A staged requirement, scenario, test, ADR or observation fact has fewer than 12 words of context. | Upsert a sectioned `document.body` (see `kibi-usage`, Entity body contract). |
 | `domain-contradictions`, `kb-consistency`, `scenario-feasibility`, `exception-claim-keys` (staged `.kb/` change) | The staged knowledge introduces a violation the last commit did not have. `kb-consistency` also catches facts that contradict only together and names their requirements. | Fix the knowledge; a contradiction with a recorded rule goes to the person (`kibi-decisions`). |
 | Proposition-complete ingestion | A staged requirement's semantic inventory is missing or no longer matches its prose. | Re-derive it (`kb_model` analyze with the complete prose) or run `kibi migrate` for drift. |
-| `kibi check-generated --staged` drift | The staged `.kb/symbols.yaml` or `.kb/symbol-coordinates.yaml` differs from a refresh computed from the index. | `kibi sync --refresh-symbol-coordinates`, review the diff, stage only the intended hunks (`git add -p`). |
+| `kibi check-generated --staged` drift | The staged `.kb/symbols.yaml` is not in the layout sync writes, or `.kb/symbol-coordinates.yaml` is tracked. | `kibi sync --refresh-symbol-coordinates`, review the diff, stage only the intended hunks (`git add -p`); untrack a tracked coordinates file with `kibi migrate` (or `git rm --cached`). |
 | `Staged impact review failed: impact_review_invalid: ...` | The base commit has `.kibi/impact-policy.json` and the staged `.kibi/impact-review.json` is missing, stale or incomplete. The message names the cause (missing review path, stale fingerprint, ...). | Prepare a fresh record (below). Any later staged change makes the fingerprints stale again, so prepare it last. |
 
 The staged gate does not judge evidence levels: the `evidence-floor` rule
@@ -98,6 +98,6 @@ does not prove it. Put the person's id there only when they reviewed it.
 npx --no-install kibi check --staged                    # the gate
 npx --no-install kibi check --staged --format json      # with full evidence
 npx --no-install kibi check-generated --staged          # manifest drift
-npx --no-install kibi sync --refresh-symbol-coordinates # refresh coordinates
+npx --no-install kibi sync --refresh-symbol-coordinates # rebuild local coordinates
 git status --short .kb                                  # what Kibi wrote
 ```

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

@@ -2,7 +2,7 @@
 id: kibi-decisions
 name: kibi-decisions
 description: "Use when the person states a rule or decision (must, never, always, from now on, we decided), when a Kibi hook asks to confirm or warns about an edit to code that implements a firm requirement, when the Stop hook says source files changed but nothing was recorded, when kb_check quotes requirement_statement_unverified, or when a request conflicts with a recorded requirement or ADR. Covers reading firmness and origin, recording a person's rule as firm with origin.ref, superseding with a Why this changed section, the kb_compile_intent unresolved/reviewCandidates/conflictReviews loop, asking before overriding a firm rule, and putting decisions to the person as one numbered kibi signoff --questions view."
-version: 1.3.0
+version: 1.4.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -80,7 +80,10 @@ name the missing capability. Never read or edit `.kb/` files directly.
   run `kibi prove`. Otherwise set `required_evidence: asserted`, say in the
   body that no end-to-end test proves the rule yet, and report it as
   asserted, not tested. Kibi's bootstrap and migration give an untested firm
-  rule the same floor.
+  rule the same floor. When the rule is a claim a certificate kind checks
+  (allowed values, transitions, a pattern, a rule over roles, a config,
+  route or schema read), a certificate test proves it instead: see
+  Certificate proof kinds in kibi-usage `resources/proof.md`.
 - **The person changes a rule:** supersede it (new requirement linked
   `supersedes` new -> old, `firmness: firm` when the old one was firm, a
   `## Why this changed` section of at least 12 words naming their instruction

package/agent-plugin/skills/kibi-decisions/resources/decision-records.md

@@ -62,7 +62,10 @@ validation, not the write.
   the `evidence-floor` check while it is recorded. Drop it (the floor goes
   back to `tested`) once an end-to-end test with a proof contract and a
   passing `kibi prove` receipt covers the rule's scenario; never set it below
-  `asserted` on a firm rule.
+  `asserted` on a firm rule. A rule that a certificate kind checks (allowed
+  values, transitions, a pattern, a rule over roles, a config, route or
+  schema read) can instead be proved by a certificate test; see Certificate
+  proof kinds in kibi-usage `resources/proof.md`.
 - Your own choice is `default`; a guess is `exploratory`. Write the value
   explicitly whenever you record a decision.
 - For strict modeling (claim keys, predicate facts) follow `kibi-usage`,

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

@@ -2,7 +2,7 @@
 id: kibi-freshness
 name: kibi-freshness
 description: Check exact Git attachment, branch migration/quarantine, compiled-store freshness, source linkage, and repair state before decisions or writes.
-version: 2.2.0
+version: 2.3.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -68,7 +68,7 @@ For every freshness, branch, or completion question, call `kb_status` first, the
 - If entities look stale, refresh context through an approved Kibi capability and then re-query.
 - When asked whether a requirement is proven, quote its `evidenceLevel` and
   `evidenceFloor` from `kb_coverage`. `pending_reproof` (receipts older than
-  the code) is stale evidence, not proof; `kibi prove` refreshes it, and
+  the code, or than a file a `source` proof read) is stale evidence, not proof; `kibi prove` refreshes it, and
   `kibi check --fresh-evidence` is the check that fails on it.
 - Preserve source-file traceability by carrying `sourceFile`, text references, and validation evidence through discovery, mutation, and completion.
 - Do not read or edit files inside `.kb` directly; use the selected Kibi interface instead.

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

@@ -2,7 +2,7 @@
 id: kibi-traceability
 name: kibi-traceability
 description: Maintain source-first requirement, scenario, test, symbol, and proof traceability through Kibi's peer interfaces.
-version: 2.2.0
+version: 2.3.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -67,7 +67,8 @@ coverage and a green check are not proof by themselves.
 
 Report each requirement's `evidenceLevel` from `kb_coverage` as it is:
 `proved` only when certificate proofs (exhaustive, typecheck, arithmetic,
-smt) derive every applicable claim, named in each contract's `proves`
+smt, rule, state_machine, regex, source) bound at code or harness scope
+derive every applicable claim (intent-scope bindings stay `tested`), named in each contract's `proves`
 (`claimSummary` and `unprovedClaims` say which are missing), `tested` for fresh passing E2E receipts,
 `asserted` when only a person stands behind it, `unverified` otherwise. Its
 `evidenceFloor` says what `kb_check`'s `evidence-floor` rule requires:

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.27.0
+version: 2.32.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -436,8 +436,10 @@ For an existing product KB that needs semantic backfill, read
 `resources/kb-improvement.md`, and `resources/proof.md` for the proof workflow.
 Each current requirement has an evidence floor (`required_evidence`, else
 `tested` when firm); certificate proof kinds (exhaustive, typecheck,
-arithmetic, smt) reach `proved` for the claims their contract names in
-`proves`, and a requirement is proved only when every claim is. When the `evidence-floor` rule fails, follow Debugging
+arithmetic, smt, rule, state_machine, regex, source) reach `proved` for the claims their contract names in
+`proves`, and a requirement is proved only when every claim is. A rule
+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`.
 
 ## Predicate Ontology Decision Tree

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

@@ -178,8 +178,14 @@ left:
   goes unhandled (a switch ending in a `never` assignment, or a
   `satisfies Record<Domain, ...>` map). Set `witness.path` and
   `domain_source`; the witness must import the domain. Kibi compiles the
-  witness itself (strict, with the workspace's TypeScript), so `typescript`
-  must be installed in the workspace.
+  witness itself (strict, with the workspace's TypeScript and the import
+  resolution and declaration files of the nearest `tsconfig.json`), so
+  `typescript` must be
+  installed in the workspace (TypeScript 7 has no compiler API: add
+  `typescript@6` as a dev dependency). With `proves`, Kibi decides each
+  claim with its own witness and reports the fields or members that break
+  it. When the test's compile failed, the rejection adds the first error
+  Kibi's own compile of the witness reports.
 - `arithmetic`: a claim on one `int` or `real` variable decided exactly from
   typed facts. Set `constraint_source: { fact_ids: [FACT-...] }` to the
   numeric `property_value` facts (one subject and property); the
@@ -187,10 +193,93 @@ left:
   exactly their constraints. To read the value from the code instead, set
   `value_source: [{ symbol_id: SYM-<constant>, export: <name> }]`; Kibi
   evaluates the number export itself and adds `variable eq value` as an
-  assumption.
+  assumption. For a count claim over a collection ("exactly 32 tools") add
+  `measure: count` and name the list, set, map or object export; Kibi uses
+  its size, so do not add a number export just for the proof. A count
+  claim needs only `value_source`. Naming the claim's own fact in
+  `constraint_source` assumes the claim: without `value_source` Kibi counts
+  that derivation as intent only (tested), and with it a code value that
+  breaks the claim shows up as contradictory assumptions, which the
+  rejection names.
+  A claim that every member of a closed set has a property ("Every currency
+  in GBP, ILS and ZAR must fail closed") is a set fact whose `property_key`
+  names the property, whose `value_set` is the members and whose operator
+  is `includes` (other members may have the property too, so two such
+  claims over different sets do not contradict). Prove it with `rule`: Kibi
+  checks the property on each listed member. The kinds that compare the
+  whole set (`exhaustive`, `state_machine`) reject an `includes` fact.
 - `smt`: an SMT-LIB query that declares the facts' property as a constant,
   asserts each `constraint_source` fact constraint and then the claim's
   negation. Kibi re-runs z3 or cvc5 on it and accepts only `unsat`.
+- `rule`: decisions over finite domains. Set `predicate_source: {<predicate>:
+  { symbol_id }}` to the function behind each predicate the claim uses (it
+  takes the arguments in order and returns a boolean) and `domains: {<type>:
+  { symbol_id }}` to the export listing each argument type's values. Kibi
+  calls every function on every combination and model checks the claim's
+  fact: a `kibi.logic.v1` rule fact (from `kb_model_requirement` with
+  `logic`) must hold for every assignment, a predicate fact must be decided
+  as it says, and a set fact whose `property_key` names a predicate needs it
+  true for every member. A type name is also a one-argument predicate
+  (`role(R)`) to range a variable. A failure names the assignment. A domain
+  can come from the project instead of an export (`domains: {<type>:
+  {source: {...}}}`, see `source` below). When the predicate is a test
+  harness that drives real code (it calls the handler with each role), add
+  `harness_for: [SYM-...]` naming that code; the claim binds with scope
+  `harness`, which proves, and those symbols must be `covered_by` the test.
+  Add `export: <name>` to a `predicate_source` entry when the function's
+  export is not the symbol's title.
+- `state_machine`: set `domain_source` to the transition table (object or
+  Map from state to next states, or `[from, to]` pairs) or to a
+  `next(state, event)` function with `domains: {state, event}`;
+  `initial_source` names the initial state. Model "transitions must be one of
+  a -> b, ..." as a `transitions` set fact (members `a->b`), and terminal,
+  initial or reachable states as `terminal_states`, `initial_states` or
+  `reachable_states` set facts; Kibi checks that projection exactly.
+  Temporal claims use two more projections: "a cancelled invoice can never
+  become paid" is a `reachable_pairs` fact with `operator: excludes` and
+  member `cancelled->paid`, and "every path from draft to paid must pass
+  through approved" is a `required_waypoints` fact with member
+  `draft->paid via approved` (paid must be reachable from draft, and not
+  once approved is removed). Any projection also takes `includes`,
+  `subset_of` and `excludes`. Rules over a machine use `transition`,
+  `reachable`, `initial`, `terminal`, `state`.
+- `regex`: set `pattern_source` to a `RegExp`, a Python `re.compile(...)` or
+  a string constant. Model "X must match `re`" as a string fact with
+  `operator: matches` (a JavaScript pattern with the `u` flag, matched
+  whole); Kibi decides exact language equality and reports the shortest
+  string only one side accepts. Backreferences, lookaround, `\b`, the `g`,
+  `y`, `m` and `v` flags, Python `\d`/`\w` without `re.ASCII` and
+  non-ASCII letters under `i` are refused with the reason. An exact string
+  fact (`eq`/`neq`) checks a constant.
+- `source`: Kibi reads a project source itself and checks a set fact
+  against what it read, so the test only runs the proof (it may write
+  nothing, or `sourceCertificate({ testId })`). Set `source: {reader, ...}`:
+  `json`/`yaml` (`file`, `path`, `select`), `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:
+  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
+  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
+  read is never silently partial. Model the claim as a set fact: `eq`
+  (exactly), `includes` (at least), `subset_of` ("must be one of"),
+  `excludes` ("must never use"); `property_key: required_fields` or
+  `nullable_fields` (only `eq`/`includes`) with bare members `name` for
+  "every table" (it also covers tables added later) or `table.name` for
+  one; `middleware` with `includes` for "every route under /p must use M"
+  (Kibi checks each route). Name middleware with `names_from`: a
+  zero-argument factory export such as `requireAuth()` names the
+  middleware it returns `requireAuth`. Write the fact with `kb_model`
+  (requirement mode, `operator` plus a list `value`) or `kb_upsert`. The
+  receipt stales when a file the read touched changes, and the claim binds
+  with scope `source`. `value_source` accepts `{source, measure: count}`.
+  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.
 
 `arithmetic` and `smt` from `constraint_source` alone prove that the
 knowledge base's facts entail the claim, not that code follows the facts:
@@ -202,8 +291,11 @@ Every certificate contract names the claims it proves in `proves:
 [CLAIM-...]` (blocking `proof-contract-claims` from schema 12). Kibi derives
 each claim's obligation from its grounding fact: a set fact (`value_type:
 set`, `value_set: [...]`) needs the `exhaustive` domain or the `typecheck`
-domain type to be exactly the set; a numeric fact needs the `arithmetic`
-claim or the negated `smt` assertion to be its constraint. The receipt
+domain type to be exactly the set (with `property_key: required_fields`,
+`typecheck` instead needs every member to be a required, non-nullable field
+of the domain type); a numeric fact needs the `arithmetic` claim or the
+negated `smt` assertion to be its constraint; rule, predicate, machine and
+string facts need the `rule`, `state_machine` or `regex` checks above. The receipt
 records one binding per claim: `derived` (checked, the only kind that
 proves), `attested` (the fact has no derivation; counts as tested) or
 `rejected` with the reason. Model an enumerated claim as a set fact and a
@@ -212,13 +304,16 @@ REQ-...` shows each claim with its bindings.
 
 Build the certificate with `kibi-cli/proof-certificates`
 (`exhaustiveCertificate`, `typecheckCertificate`, `arithmeticCertificate`,
-`smtCertificate`), fail the test when it records a failure
-(`failedMembers`), and call `writeCodeCertificate`; it writes to the
+`smtCertificate`, `ruleCertificate`, `stateMachineCertificate`,
+`regexCertificate`, `sourceCertificate`; `readProjectSource` returns Kibi's
+read for a test that wants to assert on it), fail the test when it records a failure
+(`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
 `executable_for` the test and named in `required_proofs`; the domain symbol
-`implements` the requirement and is `covered_by` the test; the test
+(and every symbol a rule, machine or pattern contract names) `implements`
+the requirement and is `covered_by` the test; the test
 `validates` one of the requirement's scenarios. `proved` is per claim: a
 multi-claim requirement is proved only when certificates derive every
 applicable claim, and reads `tested` with `n/m claims proved` otherwise. A
@@ -296,7 +391,8 @@ re-run `kibi prove --stale` (or the affected selection), then confirm
 unit test count only while that unit test has a current passing receipt, so
 prove unit tests that cover type-shape symbols too.
 
-Full reference: `docs/proving-requirements.md`.
+Full reference: [Proving requirements](https://looted.github.io/kibi/reference/proving.html)
+(`docs/proving-requirements.md` in the Kibi repository).
 
 ## Debugging proof regressions
 

package/dist/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "2.9.3",
+  "version": "2.9.6",
   "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/dist/skills/.canon-hash.json

@@ -4,27 +4,27 @@
   "kibi-bootstrap/resources/branch-lifecycle.md": "c854264ce888439140883a3fc636db5e522f020dd27b30a5c1ecc4105b64ed13",
   "kibi-bootstrap/resources/operation-access.md": "b5a6a59e72d800c376e7fad79132897623c32a0ce152a1e8d73f9628b444db51",
   "kibi-bootstrap/resources/source-authoring.md": "bf296e62f69474e01797d6cb9469bf624551dca834dd188abb6e705bd96fa586",
-  "kibi-commit-review/SKILL.md": "a20c91e8b783114b64be5d9e694d31d57dd733332cb11bacda1cd1214bdeec4f",
-  "kibi-commit-review/resources/staged-gate.md": "0c30b580b998829e9dea1b0859e9da9e5151ce8349f1b1ec1b4e43b364009e78",
-  "kibi-decisions/SKILL.md": "f0387b53abf752d10a6dc6087232dab743dbfeefe35f4335c389e08aa30fb9be",
-  "kibi-decisions/resources/decision-records.md": "203389509e3bbb1e400135b784458be9bd8e66efcc4f288dcfc8188c1f370b93",
+  "kibi-commit-review/SKILL.md": "cd3a0d5ed5e2e7562995180e440dce1aa1607d3d072d3400e966e988725ed399",
+  "kibi-commit-review/resources/staged-gate.md": "37f750f327bb9202c1f30989763f4f1205b906cf672318ca50887d7984bc3e08",
+  "kibi-decisions/SKILL.md": "02685fa50f093025782986bfe009940e934c3a64d47858920815e7eb66b0c523",
+  "kibi-decisions/resources/decision-records.md": "b201e619c48daf6ebe5989991a96f6c0573adb6c37abf814b9d34b7a1cd423c6",
   "kibi-decisions/resources/signoff-views.md": "123da13a3f2b30b5672044a1284626e218d3088411f84f2692746f95e06c1393",
-  "kibi-freshness/SKILL.md": "a1c7d7e50b52c4d41c118d1a33c50eed3980c88cc1fe10e3dea2a182d79c9105",
+  "kibi-freshness/SKILL.md": "b5c4f24bebdb5b4e0d04c2fa1176fc33ace35334b0c0b6ca943d6f445dc9b69e",
   "kibi-freshness/resources/branch-lifecycle.md": "ebc01b19fe3dca8df5fc0175978963f6f1204f71f7c805cb2a5fb1b277ac78e4",
   "kibi-freshness/resources/operation-access.md": "4e1db9294ee540cd29b8b3a2532a81e7894d5b4228b39e99ba48b37212f489f3",
   "kibi-freshness/resources/source-authoring.md": "41a0547ce4d2a112a0f3671d36720f07c447864db3b473e94eb88a8ce2d371ff",
-  "kibi-traceability/SKILL.md": "8b935e761361e309846ec8893956e8c303e41edd240a103fad9f79a00a1822e9",
+  "kibi-traceability/SKILL.md": "57323b0093dd46bed900bcd21cc1d3ba0eacb14f3580fb9e655cf366e4370e2c",
   "kibi-traceability/resources/branch-lifecycle.md": "50f1a6355aa9185d412b2474db1a64e112944625d2465be0adbf93ada3273c1f",
   "kibi-traceability/resources/operation-access.md": "39f7972ab7f4ae7479e78f7072bb50e8e6c4cdf4f857425f69d2522d37db437c",
   "kibi-traceability/resources/source-authoring.md": "408c6ee2bef1b84e0194c0538ef929c26a0a617e631b2234247388140dbbdd08",
   "kibi-traceability/resources/traceability.md": "38c290a0bc71bd1692e115f22694743946e2f69630e134acfd43cee5f613fb88",
-  "kibi-usage/SKILL.md": "e2582254ed7d9742ab2ed2b6ba07337d48e6f4678012b8d7f68e6c4b10f5767c",
+  "kibi-usage/SKILL.md": "36242e1ec0b461502d978f728d0946e654ea6e8871212ef298977c5e8e9b9767",
   "kibi-usage/resources/branch-lifecycle.md": "f1bf359e9826e83c548f3cd0287f8175a62456527b0132b06b3f9f74aa59b7d6",
   "kibi-usage/resources/fact-lanes.md": "899218f90396aa469b6e34aeb5f7ea1f38bf11bb326102319f376c213859fb33",
   "kibi-usage/resources/kb-improvement.md": "a8408fce27342bdce6415a6718599e53fe00bb33aa1fd3dc42353ec6f61adcd7",
   "kibi-usage/resources/logic-ir.md": "0e8ce8aad07433ab4803ec169149ff6c4e1cf8cf010af18fa6fd67862d9be807",
   "kibi-usage/resources/operation-access.md": "eb455796c066787ffd3fae8db0db1d3e87a84265a57f06ae61e30103cd6aed66",
-  "kibi-usage/resources/proof.md": "c51f717153b1d644636099d7355e8da23c7ceb5d53df45771148c119824d52c1",
+  "kibi-usage/resources/proof.md": "f5ce2c97b676d3302e33992e7f803c3ffbbb0aa7a808adc00e82cdba33325467",
   "kibi-usage/resources/relationship-directions.md": "0fdd67032c2d15299f772845fc4f807eb9435b09507bd87a5911ab33db2f143d",
   "kibi-usage/resources/source-authoring.md": "cad93f1e0ae08a676f2de7492f9227677880302327e74d159618fea86ca50abe",
   "kibi-usage/resources/ui-requirements.md": "f99c2a9a73bbb7bd92ce1f231db3056d544588be149a5b0d3f7cc6f28bc9eee9",

package/dist/skills/kibi-commit-review/SKILL.md

@@ -1,8 +1,8 @@
 ---
 id: kibi-commit-review
 name: kibi-commit-review
-description: "Use when kibi check --staged or the Kibi pre-commit hook blocks a commit (kibi_impact_evidence_missing, symbols_manifest_stale, symbol_granularity_violation, symbol-coverage, kibi check-generated drift, Staged impact review failed), or when preparing a commit or pull-request impact review. Covers reading the per-file Detail lines, authoring .kb/symbols.yaml symbol entries through kb_upsert, kibi sync --refresh-symbol-coordinates, staging the tracked Kibi evidence with git add, kb_prepare_impact_review for a staged or diff scope, the kibi signoff requirements summary to show before a commit, and how merge commits and migration renames are judged."
-version: 1.2.2
+description: "Use when kibi check --staged or the Kibi pre-commit hook blocks a commit (kibi_impact_evidence_missing, symbols_manifest_stale, symbol_granularity_violation, symbol-coverage, kibi check-generated drift, Staged impact review failed), or when preparing a commit or pull-request impact review. Covers reading the per-file Detail lines, authoring .kb/symbols.yaml symbol entries through kb_upsert, staging the tracked Kibi evidence with git add (symbol coordinates are derived and never staged), kb_prepare_impact_review for a staged or diff scope, the kibi signoff requirements summary to show before a commit, and how merge commits and migration renames are judged."
+version: 1.3.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -55,17 +55,17 @@ Never read or open any file under `.kb`, not even read-only with a file tool to
    - New or uncovered symbols: author a `symbol` entity per listed symbol
      through `kb_upsert` (`title` = the member the extractor names,
      `sourceFile`, `status: active`, `symbol_role: behavioral`, `implements`
-     to the requirement, `covered_by` to the test). Then run
-     `kibi sync --refresh-symbol-coordinates`.
-   - Only coordinates moved: `kibi sync --refresh-symbol-coordinates`.
+     to the requirement, `covered_by` to the test).
+   - Only lines moved: nothing to do. Symbol coordinates are derived locally
+     by every sync and never committed.
    - No behavior change (a genuine false positive): see the audited
      no-impact note in `resources/staged-gate.md`; it never covers a real
      behavior change.
 4. **Stage the evidence.** Kibi authors tracked files but never Git-stages or
    commits them. `git status --short .kb` lists what it wrote; `git add` the
-   entity Markdown, `.kb/relationships/` shards, `.kb/symbols.yaml` and
-   `.kb/symbol-coordinates.yaml` that belong to this change (use `git add -p`
-   when the files hold unrelated edits).
+   entity Markdown, `.kb/relationships/` shards and `.kb/symbols.yaml` that
+   belong to this change (use `git add -p` when the files hold unrelated
+   edits). `.kb/symbol-coordinates.yaml` is gitignored; never stage it.
 5. **Re-run** `kibi check --staged` (and `kibi check-generated --staged` when it
    failed) until it passes. Never bypass the hook (`--no-verify`) unless the
    person says so.

package/dist/skills/kibi-commit-review/resources/staged-gate.md

@@ -8,10 +8,10 @@ not the working tree, so a fix counts only once it is staged.
 ## Reading a finding
 
 ```text
-symbols_manifest_stale: .kb/symbol-coordinates.yaml is stale or missing for staged source files: src/billing/refund.ts
+symbols_manifest_stale: .kb/symbols.yaml does not cover the declarations of staged source files: src/billing/refund.ts
   Detail: src/billing/refund.ts — extraction finds 4 symbol(s), evidence covers 3.
       Not in .kb/symbols.yaml: approveRefund (line 42)
-  Suggestion: Author .kb/symbols.yaml entries for the uncovered symbols (kibi upsert, with implements/covered_by links), then run kibi sync --refresh-symbol-coordinates && git add .kb/symbol-coordinates.yaml .kb/symbols.yaml, then re-run kibi check --staged.
+  Suggestion: Author .kb/symbols.yaml entries for the uncovered symbols (kibi upsert, with implements/covered_by links). Stage .kb/symbols.yaml with the behavior edit, then re-run kibi check --staged.
 ```
 
 - Detail lines name every symbol, never a shortened list. `Evidence without a
@@ -24,15 +24,15 @@ symbols_manifest_stale: .kb/symbol-coordinates.yaml is stale or missing for stag
 
 | Id or message | Cause | Fix |
 | --- | --- | --- |
-| `kibi_impact_evidence_missing` | A staged behavior edit (changed lines in exported or behavior-bearing code, not comments or formatting) has no staged Kibi evidence. Test-only edits do not need it unless they add executable test symbols. | Query the owning knowledge; update it when behavior changed; stage entity Markdown under `.kb/`, authored `.kb/symbols.yaml` entries for the listed symbols, or refreshed `.kb/symbol-coordinates.yaml`. |
-| `symbols_manifest_stale` | Extraction output changed and the staged coordinates (or manifest) do not match it. | Author entries for the listed symbols first, then `kibi sync --refresh-symbol-coordinates`, then stage both manifests. |
+| `kibi_impact_evidence_missing` | A staged behavior edit (changed lines in exported or behavior-bearing code, not comments or formatting) has no staged Kibi evidence. Test-only edits do not need it unless they add executable test symbols. | Query the owning knowledge; update it when behavior changed; stage entity Markdown under `.kb/` or authored `.kb/symbols.yaml` entries for the listed symbols. A file whose every declaration already has a `.kb/symbols.yaml` entry needs nothing more. |
+| `symbols_manifest_stale` | A staged behavior file declares symbols `.kb/symbols.yaml` has no entry for, or an entry names a declaration that is gone. | Author entries for the listed symbols, re-point or retire entries whose declaration is gone, and stage `.kb/symbols.yaml`. Coordinates are derived locally and never staged. |
 | `symbol_granularity_violation` | A changed behavioral member is owned only by a coarse class or module symbol while a narrower declaration exists. | Add a symbol for the member itself (`title` = `Class.method` or the exported function) with its own links; use `granularity_reason` (`config-artifact`, `module-level-behavior`, `extractor-miss`, `legacy-link`, `test-suite`) only when it is true. |
 | `symbol-coverage` | A changed symbol, or a symbol whose staged manifest entry changed, fails the full-check rule on the staged knowledge. | The symbol `implements` the requirement and is `covered_by` a test that verifies it: through the requirement's scenario (`verified_by` scenario -> test) when it has one, else `verified_by` requirement -> test. A direct requirement -> test link does not count while a scenario exists. The finding's suggestion names the missing link (see `kibi-traceability`). |
 | `kibi_impact_override_missing_rationale` | A `Kibi-Impact: none` declaration has no `Rationale:` line. | Add the rationale, or drop the declaration and stage real evidence. |
 | `entity-context-missing` (staged entity) | A staged requirement, scenario, test, ADR or observation fact has fewer than 12 words of context. | Upsert a sectioned `document.body` (see `kibi-usage`, Entity body contract). |
 | `domain-contradictions`, `kb-consistency`, `scenario-feasibility`, `exception-claim-keys` (staged `.kb/` change) | The staged knowledge introduces a violation the last commit did not have. `kb-consistency` also catches facts that contradict only together and names their requirements. | Fix the knowledge; a contradiction with a recorded rule goes to the person (`kibi-decisions`). |
 | Proposition-complete ingestion | A staged requirement's semantic inventory is missing or no longer matches its prose. | Re-derive it (`kb_model` analyze with the complete prose) or run `kibi migrate` for drift. |
-| `kibi check-generated --staged` drift | The staged `.kb/symbols.yaml` or `.kb/symbol-coordinates.yaml` differs from a refresh computed from the index. | `kibi sync --refresh-symbol-coordinates`, review the diff, stage only the intended hunks (`git add -p`). |
+| `kibi check-generated --staged` drift | The staged `.kb/symbols.yaml` is not in the layout sync writes, or `.kb/symbol-coordinates.yaml` is tracked. | `kibi sync --refresh-symbol-coordinates`, review the diff, stage only the intended hunks (`git add -p`); untrack a tracked coordinates file with `kibi migrate` (or `git rm --cached`). |
 | `Staged impact review failed: impact_review_invalid: ...` | The base commit has `.kibi/impact-policy.json` and the staged `.kibi/impact-review.json` is missing, stale or incomplete. The message names the cause (missing review path, stale fingerprint, ...). | Prepare a fresh record (below). Any later staged change makes the fingerprints stale again, so prepare it last. |
 
 The staged gate does not judge evidence levels: the `evidence-floor` rule
@@ -98,6 +98,6 @@ does not prove it. Put the person's id there only when they reviewed it.
 npx --no-install kibi check --staged                    # the gate
 npx --no-install kibi check --staged --format json      # with full evidence
 npx --no-install kibi check-generated --staged          # manifest drift
-npx --no-install kibi sync --refresh-symbol-coordinates # refresh coordinates
+npx --no-install kibi sync --refresh-symbol-coordinates # rebuild local coordinates
 git status --short .kb                                  # what Kibi wrote
 ```