kibi-cursor 2.6.10 → 2.7.0

package/.cursor-plugin/plugin.json

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

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # kibi-cursor
 
+## 2.7.0
+
+### Minor Changes
+
+- 5ad4319: Requirements and ADRs can now say how firmly they were decided, so a later agent knows whether it may change a decision on evidence or must ask a human first. Mark a rule a person stated `firmness: firm` (it must cite their words in `origin.ref`, or `approval_ref` on a requirement), a guess `firmness: exploratory`, and leave the rest unset (`default`). `kibi check` now blocks a firm decision without that reference (Kibi checks that it is present, not that it is genuine), a decision that is not firm superseding a firm one, and a current requirement or ADR that supersedes another without a `## Why this changed` section naming the evidence. `kb_search` and `kb_query` show the firmness of each decision; the editor hooks label firm and exploratory ones.
+
+  Migration: this is a hard rollout with KB schema 9. Run `kibi migrate --yes` once; it records every supersede edge that predates the rule in the manifest (`supersedesReasonAcknowledged`, as `FROM -> TO`), so those do not block, and an advisory `supersedes-reason-acknowledged` diagnostic counts them. No source file is rewritten and no reason is invented. New supersedes must explain themselves, including a new one on an acknowledged decision.
+
+  Technical summary: new optional `firmness` property (`firm` | `default` | `exploratory`) on `req` and `adr` in the JSON schema, the `kb_upsert` input schema, the markdown extractor and the Prolog entity schema; the schema rejects it on other types. `kb_upsert` judges firmness as it will be written: an update that omits `firmness` keeps the stored value (also in the compiled store), and a write that leaves a decision firm without a reference is rejected. `decision-firm-superseded` checks every superseder, retired ones included, so a chain cannot launder a firm decision; shard edges from deleted entities are ignored. New rules `decision-firm-unreferenced`, `decision-firm-superseded` and `supersedes-reason-missing` (canonical, blocking) and `supersedes-reason-acknowledged` (info) read authored requirements, ADRs, front-matter `supersedes` links and relationship shards, so they agree before a sync. `LATEST_KB_SCHEMA_VERSION` is 9; the `decision-firmness-v9` migration step and the `supersedes-reason-acknowledge` fragment action write only `.kb/manifest.json`. Search answer rows and `kb_query` results carry the effective firmness of requirements and ADRs; hook snippets append `[firm]` or `[exploratory]`. The `kibi-usage` skill gains a "Decision firmness" section.
+
+### Patch Changes
+
+- adac6d1: `kb_delete` (and `kibi delete`) now treats a returned deletion plan as a result instead of an error. Deleting an entity authored in a Markdown or YAML file returns `outcome: "plan_returned"`, an empty `errors` list and a `nextActions` entry whose `input` is the exact `kb_apply_plan` call (`{plan, approvedPlanHash}`) to run unchanged; an authored requirement returns `outcome: "supersession_required"` with a `kb_upsert` supersession template. The `approvedPlanHash` input now works: repeating the delete with the plan's hash applies the freshly computed plan in one call, and a stale or different hash fails with `DELETE_PLAN_HASH_MISMATCH` without writing. A new `dryRun: true` input previews relationship and direct entity deletes (counts, source writes with hashes, skipped effects) without touching sources or the store.
+
+  Technical summary: `executeDelete` builds `nextActions` for the authored plan path, lists only real per-id failures in `errors` (plus any resolved non-authored id the plan does not cover), and on a matching `approvedPlanHash` delegates to `executeApplyPlan` under the lock it already holds, which gained an optional `onCommitted` callback so a post-commit failure is still classified as committed. Relationship deletes gain a dry-run branch after preflight that renders shard and authored-source patches without writing, using the new `planRelationshipShardRemovals` (which `removeRelationshipsFromShards` now wraps). The `kibi.kb_delete.v1` result adds optional `outcome`, `dryRun`, `wouldDelete`, `planHash`, `sourcePaths` and `recoveryJournalId`; the input schema adds `dryRun` and documents `approvedPlanHash`. MCP contract fixtures, the MCP, CLI and error references, and the bundled kibi-usage and kibi-traceability skills (with their host mirrors) are updated.
+
+- Updated dependencies [5ad4319]
+  - kibi-agent-core@0.4.0
+
+## 2.6.11
+
+### Patch Changes
+
+- b1d003a: Agents working under the Kibi host hooks now have a guide to the snippet that arrives before a read or edit: which line names the governing requirements, which lists the facts the edit must keep true, which tests prove the file, what the one-line follow-up and the unowned-file and unreadable-manifest notes mean, and which `kb_check` call to run afterwards. The modeling cheatsheet also explains where a `claim_key` comes from and how to repair a mismatch instead of editing the clause text.
+
+  Technical summary: kibi-usage 2.15.2 gains a "Reading a hook snippet" section describing the lines `kibi-agent-core/snippets` renders (`Kibi knowledge for …`, `must keep true`, `Decision`, `Covered by`, `Next layer`, the `kb_check` line, `focusUpdate`, `unownedSourceNote`, `unreadableManifestNote`); host skill mirrors are regenerated. `docs/modeling-cheatsheet.md` gains a "Claim keys" section covering derivation from `claim_text`, the `kb_model` sources of the key, the mismatch error and the grounding-target rule.
+
+- 8f3f586: Permission grants written the way product owners write them now model as permission rules. `kb_model` (mode predicates) accepted "may", "can", "is allowed to" and "are permitted to" but rejected "must be able to", "are able to", "have permission to" and "are entitled to" with "required semantic cue absent", so a requirement such as "An admin must be able to read any analysis request" ended as an ontology gap even with complete argument bindings. The semantic advisor now also treats "have permission to" and "are entitled to" as normative clauses, and inferred permission bindings drop the leading article and singularise the resource, so "any analysis request" and "analysis requests" bind the same actor, action and resource key that the allow/deny contradiction check compares.
+  - `predicate-applicability.ts`: the permission_rule cue and the normative-intent gate accept `must/shall/should be able to`, `is/are able to`, `is/are entitled to` and `has/have permission to`, including the common-verb form right after the grant.
+  - `clauses.ts`: `has/have (no) permission to` and `is/are (not) entitled to` are normative assertions; bare `is/are able to` stays descriptive so stored inventories keep their roles.
+  - `predicate-inference-1.ts`: grant and prohibition forms of the new cues bind actor, action, resource and decision; actors and resources lose their determiner and resources are singular.
+  - The builtin semantic classifier's permission signal recognises `permitted`, `able to`, `entitled to` and `permission to`.
+  - kibi-usage 2.15.1: the deny example shows the singular resource and lists the grant wordings `permission_rule` accepts.
+
 ## 2.6.10
 
 ### 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.6.10",
+  "version": "2.7.0",
   "description": "Repo-local, per-branch, queryable knowledge base. Portable Agent Plugin packaging Kibi's Agent Skills and MCP server.",
   "author": { "name": "Kibi" },
   "homepage": "https://looted.github.io/kibi/",

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

@@ -43,10 +43,12 @@ sequential `kb_upsert`, then run final check and coverage. Kibi authors tracked
 files transactionally but never Git-stages or commits them. Do not read or edit
 `.kb` directly.
 
-Use `kb_delete` only for intentional cleanup. Authored entity deletion returns a
-hash-bound approval plan; requirements normally evolve through a new
-requirement linked with `supersedes`. Relationship deletes patch shards while
-preserving unrelated records.
+Use `kb_delete` only for intentional cleanup; `dryRun: true` previews any
+delete without writing. Authored entity deletion returns `outcome:
+plan_returned` with a hash-bound plan whose `nextActions[0].input` is the exact
+`kb_apply_plan` input; requirements return `supersession_required` and evolve
+through a new requirement linked with `supersedes`. Relationship deletes patch
+shards while preserving unrelated records.
 
 ## Typed recovery and proof
 

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.15.0
+version: 2.16.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -82,6 +82,41 @@ different workspace than the one you asked for; its `detail.reason` says why.
 Use the CLI from your working directory instead: `npx --no-install kibi ...`
 runs where you are and needs no `workspaceRoot`.
 
+## Reading a hook snippet
+
+On hosts where Kibi hooks are installed, a short block
+arrives before you read or edit a file whose symbols are linked to
+requirements. It is projected from `.kb/symbols.yaml`, not from the store, so
+it is a pointer to the knowledge, never proof. Each line answers one question:
+
+- `Kibi knowledge for <path> (symbol manifest):` and the `- REQ-… — <symbol
+  titles>` rows: the requirements the file's symbols implement, lead
+  requirement first. Read the lead requirement with `kb_query({id})` before
+  changing behavior.
+- `REQ-… must keep true: FACT-…` (edit only): the ground facts the lead
+  requirement requires. An edit that breaks one of them is a requirement
+  change: supersede and remodel the requirement, do not code around the fact.
+- `Decision: ADR-…` (edit only): the decision behind the lead requirement.
+- `Covered by: TEST-…` and `Test code for: …`: the tests that prove the
+  file's symbols; run or update them with the edit.
+- `The edit is inside <symbol>, which implements REQ-…`: the symbol the edit
+  lands in.
+- `Next layer: …`: the exact `kb_query` and `kb_search(... sourceLocations)`
+  calls that return the full detail.
+- The `kb_check({sourceFiles:[…], includeImpactDiagnostics:true,
+  includeWorkingTreeDiff:true})` line (edit only): run it after the edit. The
+  Stop hook reminds you once per session of files edited without it.
+
+A file already shown this session gets only the one-line `Kibi: this edit to
+<path> is inside <symbol>` update; the facts and tests from its first snippet
+still apply. `Kibi: no symbol in <path> is linked to a requirement yet` means
+the file is unowned: find the governing requirement with `kb_search` and
+`sourceLocations`, then link a symbol to it with `implements` through
+`kb_upsert`. Without a readable manifest (`Kibi: the hook could not read
+.kb/symbols.yaml`) snippets are off for this session; `kb_query({sourceFile})`
+still answers and `kibi sync` regenerates the manifest. The search tip and the
+`.kb/` note appear once per session and need no action.
+
 ## Safe workflow
 
 1. Always discover before you mutate: start with `kb_search`, then exact-filter with `kb_query`. Use
@@ -153,8 +188,9 @@ returns `status: error`, `MIGRATION_PLAN_REFUSED` and `data.outcome:
 refused`: nothing changed, so read the action `detail` and get a new plan.
 `data.outcome: reconciliation_required` (status success) means an action
 failed mid-way: inspect its effect before retrying. `kb_delete` of an
-authored entity returns status success with `deleted: 0`; its `errors` say
-why nothing was deleted. If the status is
+authored entity returns status success with `deleted: 0` and `outcome:
+plan_returned` (or `supersession_required` for a requirement): nothing was
+deleted yet, and `nextActions` names the call that does it. If the status is
 `committed_with_repairs`, the mutation already committed: inspect failed effects,
 execute each required repair action in order, and never retry the original
 operation. Record effect failures, followed actions, and unsafe retries in
@@ -267,12 +303,18 @@ authored. Each one is the order the write path accepts.
    between the two writes `kb_check` reports the requirement until the
    second lands.
 3. **Deleting authored entities.** `kb_delete` on an authored entity that
-   is not a requirement (scenario, test, fact, ADR, …) returns a hash-bound
-   `kibi.entity-deletion-plan.v1` in `deletionPlan`; apply it unchanged with
-   `kb_apply_plan` (`plan` plus `approvedPlanHash: plan.planHash`). For an
-   authored requirement the plan carries `supersessionRequired: true` and
-   `kb_apply_plan` refuses it (`REQUIREMENT_SUPERSESSION_REQUIRED`): Kibi
-   never deletes an authored requirement. Evolve it instead with a new
+   is not a requirement (scenario, test, fact, ADR, …) writes nothing and
+   returns `outcome: plan_returned` with a hash-bound
+   `kibi.entity-deletion-plan.v1` in `deletionPlan`. After review, run
+   `nextActions[0]` unchanged: `kb_apply_plan` with its `input` (`plan` plus
+   `approvedPlanHash: plan.planHash`), or repeat the `kb_delete` call with
+   `approvedPlanHash` to apply the freshly computed plan in one step (a
+   changed source fails with `DELETE_PLAN_HASH_MISMATCH`). `dryRun: true`
+   previews relationship and direct deletes without writing. For an
+   authored requirement the result is `outcome: supersession_required`, the
+   plan carries `supersessionRequired: true` and both routes refuse it
+   (`REQUIREMENT_SUPERSESSION_REQUIRED`): Kibi never deletes an authored
+   requirement. Evolve it instead with a new
    requirement linked by `supersedes` and close the old one, or, for an
    agent-origin requirement nobody approved and nothing links to, upsert it
    with `status: closed` (keep its `title`); it stays on disk as history. A
@@ -307,6 +349,29 @@ human sets `approved_by`; `kb_check` flags approvals an agent recorded without
 corroboration. Never fill in an approval yourself. Record why a requirement
 exists in `rationale`, or link the ADR that explains it.
 
+## Decision firmness
+
+Requirements and ADRs carry `firmness`, which says what you may do with them.
+Search answers, `kb_query` rows and hook snippets show it (snippets label only
+`[firm]` and `[exploratory]`; an unlabeled decision is `default`).
+
+- `firm`: a human stated it as a rule. Follow it; to change it, ask first.
+  `kb_check` blocks a firm decision without `origin.ref` to their words, and
+  a replacement of a firm decision that is not itself firm.
+- `default` (when absent): a delegated or agent choice. Follow it unless the
+  task gives evidence against it; then supersede it in the same change and
+  list it under "Decisions I changed" for review, without asking first.
+- `exploratory`: a flagged guess; revisit it when you touch the area.
+
+Set `firmness` from what a human actually said: only their stated rule is
+`firm` (with `origin.ref`); "do whatever" or your own pick is `default`; a
+guess is `exploratory`. A supersede needs `## Why this changed` in the new
+entity's body (at least 12 words): name the evidence (a failing test, a
+measured cost, a constraint the old decision missed, a new requirement) and
+answer the old decision's reasoning; `kb_check` blocks it otherwise. A
+preference is not evidence: propose it instead of superseding. Kibi checks
+only that a firm decision has a reference; never cite words nobody said.
+
 Conditional clauses ("only when", "only if", "must not ... unless") compile
 into typed `forbid` rules linked by `requires_rule`, not property facts; one
 `kb_model` or `kb_compile_intent` cannot translate stays an `ontology_gap`.
@@ -334,6 +399,8 @@ For each relational clause, call `kb_model` with `mode: "predicates"`, that clau
 reviewed `schemaId`. If `binding_status` is `incomplete`, supply
 `argumentBindings` and retry. Persist `fact_kind: predicate` with the same
 `claim_key` / `claim_text`, then link `REQ -> fact` with `requires_predicate`.
+`claim_key` is derived from `claim_text`, so a ground fact may send the exact
+clause alone and Kibi fills the key in; a sent key must equal the derived one.
 Use `kb_model` with `mode: "requirement"` for strict scalar clauses. Use
 `fact_kind: observation` only for a true ontology gap. The manifest is not
 grounding: run `logic-coverage` so each key binds to one ground fact.
@@ -384,7 +451,17 @@ a second grounding link would fail, so keep the existing link or apply the
 `kb_delete` of the old link, requirement link; between the last two `kb_check`
 reports both `logic-coverage` and `strict-req-fact-pairing` for the
 requirement, as `expected.kbCheckAfterStep` states; run `kb_check` after the
-last step and apply `rollback` if it is not clean); `provide_argument_bindings` and `record_ontology_gap` mean
+last step and apply `rollback` if it is not clean). `keep_existing_grounding`
+means the requirement already links a predicate fact with the candidate's
+`canonical_key` (`existingGrounding[].matchedBy` is `canonical_key` when the
+claim was worded differently), so write nothing. `extend_requirement` means
+the requirement's proposition ledger has no entry for this text, so a link
+cannot be made and no fact is planned: add the clause to the requirement's
+prose (`mode: "requirement"`, or `kb_upsert` with the extended `semantic_text`
+and the ledger `mode: "analyze"` returns) and call `mode: "predicates"` again.
+Read `decisionConflicts` and its warnings whenever `plan` is null: they name
+the stored decision facts the candidate would contradict and the requirements
+that own them. `provide_argument_bindings` and `record_ontology_gap` mean
 the same as for an ungrounded claim, and the gap observation is not a grounding
 link, so write it exactly as returned (tags, `claim_text`, `document.body`, no
 `claim_key`, no relationships). Record an ontology gap only when no returned schema fits the

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

@@ -6,7 +6,7 @@ Requirement prose remains the human-readable source. Facts add queryable semanti
 
 Logical coverage is clause-based, not entity-based. Give `kb_model` (`mode: "analyze"`) the complete requirement body and verify that its `clauses` list contains every atomic obligation. Supply the `clauses` input yourself when automatic splitting would combine or omit obligations. For every normative clause:
 
-- preserve the returned stable key as `claim_key` and the exact clause as `claim_text` on its ground fact;
+- put the exact clause as `claim_text` on its ground fact, with the returned stable key as `claim_key` or none (Kibi derives a missing key; a sent key must match);
 - add the key to the exact current `logic_claims` set, removing only stale keys whose propositions no longer exist in the source;
 - link it through exactly one `requires_property` for `property_value`, one `requires_predicate` for `predicate`, or one `requires_rule` for a safe `rule` fact;
 - leave ambiguity and ontology gaps visibly unresolved—observations do not satisfy `logic-coverage`.
@@ -68,14 +68,16 @@ id: FACT-SUSPENDED-PUBLISH-DENIED
 status: active
 fact_kind: predicate
 predicate_name: permission_rule
-predicate_args: [suspended_user, publish, articles, deny]
+predicate_args: [suspended_user, publish, article, deny]
 polarity: deny
-canonical_key: permission_rule(suspended_user,publish,articles,deny)
+canonical_key: permission_rule(suspended_user,publish,article,deny)
 claim_key: <advisor-issued key for this exact clause>
 claim_text: Suspended users must not publish articles.
 relationship: { type: requires_predicate, from: REQ-SUSPENDED-PUBLISH-DENIED, to: FACT-SUSPENDED-PUBLISH-DENIED }
 ```
 
+Inferred bindings drop the article and singularise the resource (`articles` becomes `article`, `any analysis request` and `analysis requests` both become `analysis_request`), so an allow and a deny on the same actor, action and resource share one key. Grants read the same as `allowed`: `may`, `can`, `is allowed to`, `are permitted to`, `must be able to`, `are able to`, `have permission to` and `are entitled to` all select `permission_rule` with `polarity: assert`.
+
 If another current requirement links an `assert` fact with the same predicate namespace, name, and ordered arguments, `domain-contradictions` reports the pair. More complex semantic conflicts require a shared canonical schema and arguments; do not assume Kibi can prove arbitrary equivalence between differently shaped predicates.
 
 The full logical representation of a requirement is the conjunction of all of its linked ground property and predicate terms. Conditions, exceptions, permissions, and ordering constraints remain explicit arguments of their declared schemas. Contradiction detection therefore depends on equivalent prose reusing the same predicate name, argument roles, ordered canonical values, and opposing polarity rather than inventing synonymous terms.

package/agent-plugin/skills/kibi-usage/resources/source-authoring.md

@@ -23,8 +23,10 @@ drift diagnostic. Unresolved Git index conflicts are likewise blocking; Kibi
 never chooses a merge winner.
 
 Relationship upserts and relationship deletes patch only the canonical shard,
-preserving unrelated records. Authored entity deletion returns a hash-bound
-plan; approve that plan through `kb_apply_plan`. Evolve requirements with a new
+preserving unrelated records. Authored entity deletion writes nothing and
+returns a hash-bound plan (`outcome: plan_returned`); approve it by running the
+returned `nextActions[0]` (`kb_apply_plan` with `{plan, approvedPlanHash}`)
+unchanged, or by repeating `kb_delete` with `approvedPlanHash`. Evolve requirements with a new
 requirement and `supersedes`, rather than deleting the old semantic claim.
 
 On `committed_with_repairs`, inspect `effects` and execute the typed required

package/agent-plugin/skills/kibi-usage/resources/ui-requirements.md

@@ -126,8 +126,8 @@ diagnostics (`symbol_semantic_review_needed`).
    `requires_predicate`.
 3. Scalar placement/alignment/order clauses: `kb_model` (`mode: "requirement"`), apply the strict
    subject/property plan and `constrains` / `requires_property`.
-4. Preserve `claim_key` / `claim_text`; merge every key into the requirement
-   `logic_claims` manifest.
+4. Preserve `claim_key` / `claim_text` (a missing key is derived from the
+   text); merge every key into the requirement `logic_claims` manifest.
 5. `kb_upsert` with `dryRun: true`, create endpoints first, then sequential `kb_upsert`.
 6. `kb_check` with `logic-coverage`, `predicate-verifiability`, `domain-contradictions`,
    then a final unfiltered `kb_check`.

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

@@ -203,7 +203,7 @@ Optional per-project workflow for recording what the screen should look like. No
 2. Run `kb_model` with `mode: "analyze"` on the description; audit or supply `clauses`.
 3. For relational layout clauses ("X must remain visually aligned with Y"), call `kb_model` with `mode: "predicates"`, apply the returned `fact_kind: predicate` plan with `predicate_name: visual_layout_rule` and `requires_predicate`.
 4. For scalar placement, alignment, and ordering clauses, call `kb_model` with `mode: "requirement"` and apply strict `fact_kind: subject` / `fact_kind: property_value` facts linked with `constrains` / `requires_property`. Model header order as indexed property keys (`nav_order_1`, `nav_order_2`, ...) against one subject region.
-5. Preserve `claim_key` / `claim_text` on every ground fact and merge every key into the requirement `logic_claims` manifest.
+5. Preserve `claim_key` / `claim_text` on every ground fact (a missing `claim_key` is derived from `claim_text`) and merge every key into the requirement `logic_claims` manifest.
 6. Model UI components as `symbol` entities with `sourceFile` and `symbol_role: behavioral`, linked `implements` to the requirement.
 7. `kb_upsert` with `dryRun: true`, create endpoints first, then sequential `kb_upsert`. Run `kb_check` with `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`, then a final unfiltered `kb_check`.
 

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

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

package/dist/skills/.canon-hash.json

@@ -8,20 +8,20 @@
   "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": "e3d559e149f11792a44fe9ae9d68f88933df9992df460abac33c8bfc468ddadb",
+  "kibi-traceability/SKILL.md": "df564438228efaf73740037ef4b1969b0638a6530a9385c9e7bf21108e8a952d",
   "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": "82d50af1b0921275be2cf58879d3a5d148ee171ec67d78872fbf1ea385bc8b13",
+  "kibi-usage/SKILL.md": "cc1ad5253a21ba6ceb998714cb908925bae14cf29af0c4f7f230c6ed6556a2bc",
   "kibi-usage/resources/branch-lifecycle.md": "f1bf359e9826e83c548f3cd0287f8175a62456527b0132b06b3f9f74aa59b7d6",
-  "kibi-usage/resources/fact-lanes.md": "e95c4a729264c81dd45100a4915fdf4f2dead19ce1fa0a0667da90b5e18e06ae",
+  "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": "2348819078034dd3df25664c4c707ff98f17520bbbd335bff4f48611cf672bb3",
   "kibi-usage/resources/relationship-directions.md": "0fdd67032c2d15299f772845fc4f807eb9435b09507bd87a5911ab33db2f143d",
-  "kibi-usage/resources/source-authoring.md": "a29d411fe86e6e29ce364e4ad5925bda40127c4b328a4c657d5b5f0d9fe98ff1",
-  "kibi-usage/resources/ui-requirements.md": "47a42dccbabe1e636d6b89e19e21e1ac0704b6d46a577d913e1482435ab7afb8",
-  "kibi-usage/resources/workflows.md": "bbc63bc5fb9d2fa0900f5b1be91558abe2ef4fe4c32d90204f09f03e3ffd6e4a"
+  "kibi-usage/resources/source-authoring.md": "cad93f1e0ae08a676f2de7492f9227677880302327e74d159618fea86ca50abe",
+  "kibi-usage/resources/ui-requirements.md": "f99c2a9a73bbb7bd92ce1f231db3056d544588be149a5b0d3f7cc6f28bc9eee9",
+  "kibi-usage/resources/workflows.md": "36e7511c1b1b66dc59e8332501225cf121f0e0ce61d0b5870a052afc237f8ed9"
 }

package/dist/skills/kibi-traceability/SKILL.md

@@ -43,10 +43,12 @@ sequential `kb_upsert`, then run final check and coverage. Kibi authors tracked
 files transactionally but never Git-stages or commits them. Do not read or edit
 `.kb` directly.
 
-Use `kb_delete` only for intentional cleanup. Authored entity deletion returns a
-hash-bound approval plan; requirements normally evolve through a new
-requirement linked with `supersedes`. Relationship deletes patch shards while
-preserving unrelated records.
+Use `kb_delete` only for intentional cleanup; `dryRun: true` previews any
+delete without writing. Authored entity deletion returns `outcome:
+plan_returned` with a hash-bound plan whose `nextActions[0].input` is the exact
+`kb_apply_plan` input; requirements return `supersession_required` and evolve
+through a new requirement linked with `supersedes`. Relationship deletes patch
+shards while preserving unrelated records.
 
 ## Typed recovery and proof
 

package/dist/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.15.0
+version: 2.16.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -82,6 +82,41 @@ different workspace than the one you asked for; its `detail.reason` says why.
 Use the CLI from your working directory instead: `npx --no-install kibi ...`
 runs where you are and needs no `workspaceRoot`.
 
+## Reading a hook snippet
+
+On hosts where Kibi hooks are installed, a short block
+arrives before you read or edit a file whose symbols are linked to
+requirements. It is projected from `.kb/symbols.yaml`, not from the store, so
+it is a pointer to the knowledge, never proof. Each line answers one question:
+
+- `Kibi knowledge for <path> (symbol manifest):` and the `- REQ-… — <symbol
+  titles>` rows: the requirements the file's symbols implement, lead
+  requirement first. Read the lead requirement with `kb_query({id})` before
+  changing behavior.
+- `REQ-… must keep true: FACT-…` (edit only): the ground facts the lead
+  requirement requires. An edit that breaks one of them is a requirement
+  change: supersede and remodel the requirement, do not code around the fact.
+- `Decision: ADR-…` (edit only): the decision behind the lead requirement.
+- `Covered by: TEST-…` and `Test code for: …`: the tests that prove the
+  file's symbols; run or update them with the edit.
+- `The edit is inside <symbol>, which implements REQ-…`: the symbol the edit
+  lands in.
+- `Next layer: …`: the exact `kb_query` and `kb_search(... sourceLocations)`
+  calls that return the full detail.
+- The `kb_check({sourceFiles:[…], includeImpactDiagnostics:true,
+  includeWorkingTreeDiff:true})` line (edit only): run it after the edit. The
+  Stop hook reminds you once per session of files edited without it.
+
+A file already shown this session gets only the one-line `Kibi: this edit to
+<path> is inside <symbol>` update; the facts and tests from its first snippet
+still apply. `Kibi: no symbol in <path> is linked to a requirement yet` means
+the file is unowned: find the governing requirement with `kb_search` and
+`sourceLocations`, then link a symbol to it with `implements` through
+`kb_upsert`. Without a readable manifest (`Kibi: the hook could not read
+.kb/symbols.yaml`) snippets are off for this session; `kb_query({sourceFile})`
+still answers and `kibi sync` regenerates the manifest. The search tip and the
+`.kb/` note appear once per session and need no action.
+
 ## Safe workflow
 
 1. Always discover before you mutate: start with `kb_search`, then exact-filter with `kb_query`. Use
@@ -153,8 +188,9 @@ returns `status: error`, `MIGRATION_PLAN_REFUSED` and `data.outcome:
 refused`: nothing changed, so read the action `detail` and get a new plan.
 `data.outcome: reconciliation_required` (status success) means an action
 failed mid-way: inspect its effect before retrying. `kb_delete` of an
-authored entity returns status success with `deleted: 0`; its `errors` say
-why nothing was deleted. If the status is
+authored entity returns status success with `deleted: 0` and `outcome:
+plan_returned` (or `supersession_required` for a requirement): nothing was
+deleted yet, and `nextActions` names the call that does it. If the status is
 `committed_with_repairs`, the mutation already committed: inspect failed effects,
 execute each required repair action in order, and never retry the original
 operation. Record effect failures, followed actions, and unsafe retries in
@@ -267,12 +303,18 @@ authored. Each one is the order the write path accepts.
    between the two writes `kb_check` reports the requirement until the
    second lands.
 3. **Deleting authored entities.** `kb_delete` on an authored entity that
-   is not a requirement (scenario, test, fact, ADR, …) returns a hash-bound
-   `kibi.entity-deletion-plan.v1` in `deletionPlan`; apply it unchanged with
-   `kb_apply_plan` (`plan` plus `approvedPlanHash: plan.planHash`). For an
-   authored requirement the plan carries `supersessionRequired: true` and
-   `kb_apply_plan` refuses it (`REQUIREMENT_SUPERSESSION_REQUIRED`): Kibi
-   never deletes an authored requirement. Evolve it instead with a new
+   is not a requirement (scenario, test, fact, ADR, …) writes nothing and
+   returns `outcome: plan_returned` with a hash-bound
+   `kibi.entity-deletion-plan.v1` in `deletionPlan`. After review, run
+   `nextActions[0]` unchanged: `kb_apply_plan` with its `input` (`plan` plus
+   `approvedPlanHash: plan.planHash`), or repeat the `kb_delete` call with
+   `approvedPlanHash` to apply the freshly computed plan in one step (a
+   changed source fails with `DELETE_PLAN_HASH_MISMATCH`). `dryRun: true`
+   previews relationship and direct deletes without writing. For an
+   authored requirement the result is `outcome: supersession_required`, the
+   plan carries `supersessionRequired: true` and both routes refuse it
+   (`REQUIREMENT_SUPERSESSION_REQUIRED`): Kibi never deletes an authored
+   requirement. Evolve it instead with a new
    requirement linked by `supersedes` and close the old one, or, for an
    agent-origin requirement nobody approved and nothing links to, upsert it
    with `status: closed` (keep its `title`); it stays on disk as history. A
@@ -307,6 +349,29 @@ human sets `approved_by`; `kb_check` flags approvals an agent recorded without
 corroboration. Never fill in an approval yourself. Record why a requirement
 exists in `rationale`, or link the ADR that explains it.
 
+## Decision firmness
+
+Requirements and ADRs carry `firmness`, which says what you may do with them.
+Search answers, `kb_query` rows and hook snippets show it (snippets label only
+`[firm]` and `[exploratory]`; an unlabeled decision is `default`).
+
+- `firm`: a human stated it as a rule. Follow it; to change it, ask first.
+  `kb_check` blocks a firm decision without `origin.ref` to their words, and
+  a replacement of a firm decision that is not itself firm.
+- `default` (when absent): a delegated or agent choice. Follow it unless the
+  task gives evidence against it; then supersede it in the same change and
+  list it under "Decisions I changed" for review, without asking first.
+- `exploratory`: a flagged guess; revisit it when you touch the area.
+
+Set `firmness` from what a human actually said: only their stated rule is
+`firm` (with `origin.ref`); "do whatever" or your own pick is `default`; a
+guess is `exploratory`. A supersede needs `## Why this changed` in the new
+entity's body (at least 12 words): name the evidence (a failing test, a
+measured cost, a constraint the old decision missed, a new requirement) and
+answer the old decision's reasoning; `kb_check` blocks it otherwise. A
+preference is not evidence: propose it instead of superseding. Kibi checks
+only that a firm decision has a reference; never cite words nobody said.
+
 Conditional clauses ("only when", "only if", "must not ... unless") compile
 into typed `forbid` rules linked by `requires_rule`, not property facts; one
 `kb_model` or `kb_compile_intent` cannot translate stays an `ontology_gap`.
@@ -334,6 +399,8 @@ For each relational clause, call `kb_model` with `mode: "predicates"`, that clau
 reviewed `schemaId`. If `binding_status` is `incomplete`, supply
 `argumentBindings` and retry. Persist `fact_kind: predicate` with the same
 `claim_key` / `claim_text`, then link `REQ -> fact` with `requires_predicate`.
+`claim_key` is derived from `claim_text`, so a ground fact may send the exact
+clause alone and Kibi fills the key in; a sent key must equal the derived one.
 Use `kb_model` with `mode: "requirement"` for strict scalar clauses. Use
 `fact_kind: observation` only for a true ontology gap. The manifest is not
 grounding: run `logic-coverage` so each key binds to one ground fact.
@@ -384,7 +451,17 @@ a second grounding link would fail, so keep the existing link or apply the
 `kb_delete` of the old link, requirement link; between the last two `kb_check`
 reports both `logic-coverage` and `strict-req-fact-pairing` for the
 requirement, as `expected.kbCheckAfterStep` states; run `kb_check` after the
-last step and apply `rollback` if it is not clean); `provide_argument_bindings` and `record_ontology_gap` mean
+last step and apply `rollback` if it is not clean). `keep_existing_grounding`
+means the requirement already links a predicate fact with the candidate's
+`canonical_key` (`existingGrounding[].matchedBy` is `canonical_key` when the
+claim was worded differently), so write nothing. `extend_requirement` means
+the requirement's proposition ledger has no entry for this text, so a link
+cannot be made and no fact is planned: add the clause to the requirement's
+prose (`mode: "requirement"`, or `kb_upsert` with the extended `semantic_text`
+and the ledger `mode: "analyze"` returns) and call `mode: "predicates"` again.
+Read `decisionConflicts` and its warnings whenever `plan` is null: they name
+the stored decision facts the candidate would contradict and the requirements
+that own them. `provide_argument_bindings` and `record_ontology_gap` mean
 the same as for an ungrounded claim, and the gap observation is not a grounding
 link, so write it exactly as returned (tags, `claim_text`, `document.body`, no
 `claim_key`, no relationships). Record an ontology gap only when no returned schema fits the

package/dist/skills/kibi-usage/resources/fact-lanes.md

@@ -6,7 +6,7 @@ Requirement prose remains the human-readable source. Facts add queryable semanti
 
 Logical coverage is clause-based, not entity-based. Give `kb_model` (`mode: "analyze"`) the complete requirement body and verify that its `clauses` list contains every atomic obligation. Supply the `clauses` input yourself when automatic splitting would combine or omit obligations. For every normative clause:
 
-- preserve the returned stable key as `claim_key` and the exact clause as `claim_text` on its ground fact;
+- put the exact clause as `claim_text` on its ground fact, with the returned stable key as `claim_key` or none (Kibi derives a missing key; a sent key must match);
 - add the key to the exact current `logic_claims` set, removing only stale keys whose propositions no longer exist in the source;
 - link it through exactly one `requires_property` for `property_value`, one `requires_predicate` for `predicate`, or one `requires_rule` for a safe `rule` fact;
 - leave ambiguity and ontology gaps visibly unresolved—observations do not satisfy `logic-coverage`.
@@ -68,14 +68,16 @@ id: FACT-SUSPENDED-PUBLISH-DENIED
 status: active
 fact_kind: predicate
 predicate_name: permission_rule
-predicate_args: [suspended_user, publish, articles, deny]
+predicate_args: [suspended_user, publish, article, deny]
 polarity: deny
-canonical_key: permission_rule(suspended_user,publish,articles,deny)
+canonical_key: permission_rule(suspended_user,publish,article,deny)
 claim_key: <advisor-issued key for this exact clause>
 claim_text: Suspended users must not publish articles.
 relationship: { type: requires_predicate, from: REQ-SUSPENDED-PUBLISH-DENIED, to: FACT-SUSPENDED-PUBLISH-DENIED }
 ```
 
+Inferred bindings drop the article and singularise the resource (`articles` becomes `article`, `any analysis request` and `analysis requests` both become `analysis_request`), so an allow and a deny on the same actor, action and resource share one key. Grants read the same as `allowed`: `may`, `can`, `is allowed to`, `are permitted to`, `must be able to`, `are able to`, `have permission to` and `are entitled to` all select `permission_rule` with `polarity: assert`.
+
 If another current requirement links an `assert` fact with the same predicate namespace, name, and ordered arguments, `domain-contradictions` reports the pair. More complex semantic conflicts require a shared canonical schema and arguments; do not assume Kibi can prove arbitrary equivalence between differently shaped predicates.
 
 The full logical representation of a requirement is the conjunction of all of its linked ground property and predicate terms. Conditions, exceptions, permissions, and ordering constraints remain explicit arguments of their declared schemas. Contradiction detection therefore depends on equivalent prose reusing the same predicate name, argument roles, ordered canonical values, and opposing polarity rather than inventing synonymous terms.

package/dist/skills/kibi-usage/resources/source-authoring.md

@@ -23,8 +23,10 @@ drift diagnostic. Unresolved Git index conflicts are likewise blocking; Kibi
 never chooses a merge winner.
 
 Relationship upserts and relationship deletes patch only the canonical shard,
-preserving unrelated records. Authored entity deletion returns a hash-bound
-plan; approve that plan through `kb_apply_plan`. Evolve requirements with a new
+preserving unrelated records. Authored entity deletion writes nothing and
+returns a hash-bound plan (`outcome: plan_returned`); approve it by running the
+returned `nextActions[0]` (`kb_apply_plan` with `{plan, approvedPlanHash}`)
+unchanged, or by repeating `kb_delete` with `approvedPlanHash`. Evolve requirements with a new
 requirement and `supersedes`, rather than deleting the old semantic claim.
 
 On `committed_with_repairs`, inspect `effects` and execute the typed required

package/dist/skills/kibi-usage/resources/ui-requirements.md

@@ -126,8 +126,8 @@ diagnostics (`symbol_semantic_review_needed`).
    `requires_predicate`.
 3. Scalar placement/alignment/order clauses: `kb_model` (`mode: "requirement"`), apply the strict
    subject/property plan and `constrains` / `requires_property`.
-4. Preserve `claim_key` / `claim_text`; merge every key into the requirement
-   `logic_claims` manifest.
+4. Preserve `claim_key` / `claim_text` (a missing key is derived from the
+   text); merge every key into the requirement `logic_claims` manifest.
 5. `kb_upsert` with `dryRun: true`, create endpoints first, then sequential `kb_upsert`.
 6. `kb_check` with `logic-coverage`, `predicate-verifiability`, `domain-contradictions`,
    then a final unfiltered `kb_check`.

package/dist/skills/kibi-usage/resources/workflows.md

@@ -203,7 +203,7 @@ Optional per-project workflow for recording what the screen should look like. No
 2. Run `kb_model` with `mode: "analyze"` on the description; audit or supply `clauses`.
 3. For relational layout clauses ("X must remain visually aligned with Y"), call `kb_model` with `mode: "predicates"`, apply the returned `fact_kind: predicate` plan with `predicate_name: visual_layout_rule` and `requires_predicate`.
 4. For scalar placement, alignment, and ordering clauses, call `kb_model` with `mode: "requirement"` and apply strict `fact_kind: subject` / `fact_kind: property_value` facts linked with `constrains` / `requires_property`. Model header order as indexed property keys (`nav_order_1`, `nav_order_2`, ...) against one subject region.
-5. Preserve `claim_key` / `claim_text` on every ground fact and merge every key into the requirement `logic_claims` manifest.
+5. Preserve `claim_key` / `claim_text` on every ground fact (a missing `claim_key` is derived from `claim_text`) and merge every key into the requirement `logic_claims` manifest.
 6. Model UI components as `symbol` entities with `sourceFile` and `symbol_role: behavioral`, linked `implements` to the requirement.
 7. `kb_upsert` with `dryRun: true`, create endpoints first, then sequential `kb_upsert`. Run `kb_check` with `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`, then a final unfiltered `kb_check`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cursor",
-  "version": "2.6.10",
+  "version": "2.7.0",
   "description": "Kibi Cursor plugin - thin adapter for Cursor MCP integration and editor hooks",
   "type": "module",
   "main": "dist/index.js",
@@ -59,7 +59,7 @@
     }
   },
   "dependencies": {
-    "kibi-agent-core": "^0.3.0"
+    "kibi-agent-core": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "latest",

package/skills/.canon-hash.json

@@ -8,20 +8,20 @@
   "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": "e3d559e149f11792a44fe9ae9d68f88933df9992df460abac33c8bfc468ddadb",
+  "kibi-traceability/SKILL.md": "df564438228efaf73740037ef4b1969b0638a6530a9385c9e7bf21108e8a952d",
   "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": "82d50af1b0921275be2cf58879d3a5d148ee171ec67d78872fbf1ea385bc8b13",
+  "kibi-usage/SKILL.md": "cc1ad5253a21ba6ceb998714cb908925bae14cf29af0c4f7f230c6ed6556a2bc",
   "kibi-usage/resources/branch-lifecycle.md": "f1bf359e9826e83c548f3cd0287f8175a62456527b0132b06b3f9f74aa59b7d6",
-  "kibi-usage/resources/fact-lanes.md": "e95c4a729264c81dd45100a4915fdf4f2dead19ce1fa0a0667da90b5e18e06ae",
+  "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": "2348819078034dd3df25664c4c707ff98f17520bbbd335bff4f48611cf672bb3",
   "kibi-usage/resources/relationship-directions.md": "0fdd67032c2d15299f772845fc4f807eb9435b09507bd87a5911ab33db2f143d",
-  "kibi-usage/resources/source-authoring.md": "a29d411fe86e6e29ce364e4ad5925bda40127c4b328a4c657d5b5f0d9fe98ff1",
-  "kibi-usage/resources/ui-requirements.md": "47a42dccbabe1e636d6b89e19e21e1ac0704b6d46a577d913e1482435ab7afb8",
-  "kibi-usage/resources/workflows.md": "bbc63bc5fb9d2fa0900f5b1be91558abe2ef4fe4c32d90204f09f03e3ffd6e4a"
+  "kibi-usage/resources/source-authoring.md": "cad93f1e0ae08a676f2de7492f9227677880302327e74d159618fea86ca50abe",
+  "kibi-usage/resources/ui-requirements.md": "f99c2a9a73bbb7bd92ce1f231db3056d544588be149a5b0d3f7cc6f28bc9eee9",
+  "kibi-usage/resources/workflows.md": "36e7511c1b1b66dc59e8332501225cf121f0e0ce61d0b5870a052afc237f8ed9"
 }

package/skills/kibi-traceability/SKILL.md

@@ -43,10 +43,12 @@ sequential `kb_upsert`, then run final check and coverage. Kibi authors tracked
 files transactionally but never Git-stages or commits them. Do not read or edit
 `.kb` directly.
 
-Use `kb_delete` only for intentional cleanup. Authored entity deletion returns a
-hash-bound approval plan; requirements normally evolve through a new
-requirement linked with `supersedes`. Relationship deletes patch shards while
-preserving unrelated records.
+Use `kb_delete` only for intentional cleanup; `dryRun: true` previews any
+delete without writing. Authored entity deletion returns `outcome:
+plan_returned` with a hash-bound plan whose `nextActions[0].input` is the exact
+`kb_apply_plan` input; requirements return `supersession_required` and evolve
+through a new requirement linked with `supersedes`. Relationship deletes patch
+shards while preserving unrelated records.
 
 ## Typed recovery and proof
 

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.15.0
+version: 2.16.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -82,6 +82,41 @@ different workspace than the one you asked for; its `detail.reason` says why.
 Use the CLI from your working directory instead: `npx --no-install kibi ...`
 runs where you are and needs no `workspaceRoot`.
 
+## Reading a hook snippet
+
+On hosts where Kibi hooks are installed, a short block
+arrives before you read or edit a file whose symbols are linked to
+requirements. It is projected from `.kb/symbols.yaml`, not from the store, so
+it is a pointer to the knowledge, never proof. Each line answers one question:
+
+- `Kibi knowledge for <path> (symbol manifest):` and the `- REQ-… — <symbol
+  titles>` rows: the requirements the file's symbols implement, lead
+  requirement first. Read the lead requirement with `kb_query({id})` before
+  changing behavior.
+- `REQ-… must keep true: FACT-…` (edit only): the ground facts the lead
+  requirement requires. An edit that breaks one of them is a requirement
+  change: supersede and remodel the requirement, do not code around the fact.
+- `Decision: ADR-…` (edit only): the decision behind the lead requirement.
+- `Covered by: TEST-…` and `Test code for: …`: the tests that prove the
+  file's symbols; run or update them with the edit.
+- `The edit is inside <symbol>, which implements REQ-…`: the symbol the edit
+  lands in.
+- `Next layer: …`: the exact `kb_query` and `kb_search(... sourceLocations)`
+  calls that return the full detail.
+- The `kb_check({sourceFiles:[…], includeImpactDiagnostics:true,
+  includeWorkingTreeDiff:true})` line (edit only): run it after the edit. The
+  Stop hook reminds you once per session of files edited without it.
+
+A file already shown this session gets only the one-line `Kibi: this edit to
+<path> is inside <symbol>` update; the facts and tests from its first snippet
+still apply. `Kibi: no symbol in <path> is linked to a requirement yet` means
+the file is unowned: find the governing requirement with `kb_search` and
+`sourceLocations`, then link a symbol to it with `implements` through
+`kb_upsert`. Without a readable manifest (`Kibi: the hook could not read
+.kb/symbols.yaml`) snippets are off for this session; `kb_query({sourceFile})`
+still answers and `kibi sync` regenerates the manifest. The search tip and the
+`.kb/` note appear once per session and need no action.
+
 ## Safe workflow
 
 1. Always discover before you mutate: start with `kb_search`, then exact-filter with `kb_query`. Use
@@ -153,8 +188,9 @@ returns `status: error`, `MIGRATION_PLAN_REFUSED` and `data.outcome:
 refused`: nothing changed, so read the action `detail` and get a new plan.
 `data.outcome: reconciliation_required` (status success) means an action
 failed mid-way: inspect its effect before retrying. `kb_delete` of an
-authored entity returns status success with `deleted: 0`; its `errors` say
-why nothing was deleted. If the status is
+authored entity returns status success with `deleted: 0` and `outcome:
+plan_returned` (or `supersession_required` for a requirement): nothing was
+deleted yet, and `nextActions` names the call that does it. If the status is
 `committed_with_repairs`, the mutation already committed: inspect failed effects,
 execute each required repair action in order, and never retry the original
 operation. Record effect failures, followed actions, and unsafe retries in
@@ -267,12 +303,18 @@ authored. Each one is the order the write path accepts.
    between the two writes `kb_check` reports the requirement until the
    second lands.
 3. **Deleting authored entities.** `kb_delete` on an authored entity that
-   is not a requirement (scenario, test, fact, ADR, …) returns a hash-bound
-   `kibi.entity-deletion-plan.v1` in `deletionPlan`; apply it unchanged with
-   `kb_apply_plan` (`plan` plus `approvedPlanHash: plan.planHash`). For an
-   authored requirement the plan carries `supersessionRequired: true` and
-   `kb_apply_plan` refuses it (`REQUIREMENT_SUPERSESSION_REQUIRED`): Kibi
-   never deletes an authored requirement. Evolve it instead with a new
+   is not a requirement (scenario, test, fact, ADR, …) writes nothing and
+   returns `outcome: plan_returned` with a hash-bound
+   `kibi.entity-deletion-plan.v1` in `deletionPlan`. After review, run
+   `nextActions[0]` unchanged: `kb_apply_plan` with its `input` (`plan` plus
+   `approvedPlanHash: plan.planHash`), or repeat the `kb_delete` call with
+   `approvedPlanHash` to apply the freshly computed plan in one step (a
+   changed source fails with `DELETE_PLAN_HASH_MISMATCH`). `dryRun: true`
+   previews relationship and direct deletes without writing. For an
+   authored requirement the result is `outcome: supersession_required`, the
+   plan carries `supersessionRequired: true` and both routes refuse it
+   (`REQUIREMENT_SUPERSESSION_REQUIRED`): Kibi never deletes an authored
+   requirement. Evolve it instead with a new
    requirement linked by `supersedes` and close the old one, or, for an
    agent-origin requirement nobody approved and nothing links to, upsert it
    with `status: closed` (keep its `title`); it stays on disk as history. A
@@ -307,6 +349,29 @@ human sets `approved_by`; `kb_check` flags approvals an agent recorded without
 corroboration. Never fill in an approval yourself. Record why a requirement
 exists in `rationale`, or link the ADR that explains it.
 
+## Decision firmness
+
+Requirements and ADRs carry `firmness`, which says what you may do with them.
+Search answers, `kb_query` rows and hook snippets show it (snippets label only
+`[firm]` and `[exploratory]`; an unlabeled decision is `default`).
+
+- `firm`: a human stated it as a rule. Follow it; to change it, ask first.
+  `kb_check` blocks a firm decision without `origin.ref` to their words, and
+  a replacement of a firm decision that is not itself firm.
+- `default` (when absent): a delegated or agent choice. Follow it unless the
+  task gives evidence against it; then supersede it in the same change and
+  list it under "Decisions I changed" for review, without asking first.
+- `exploratory`: a flagged guess; revisit it when you touch the area.
+
+Set `firmness` from what a human actually said: only their stated rule is
+`firm` (with `origin.ref`); "do whatever" or your own pick is `default`; a
+guess is `exploratory`. A supersede needs `## Why this changed` in the new
+entity's body (at least 12 words): name the evidence (a failing test, a
+measured cost, a constraint the old decision missed, a new requirement) and
+answer the old decision's reasoning; `kb_check` blocks it otherwise. A
+preference is not evidence: propose it instead of superseding. Kibi checks
+only that a firm decision has a reference; never cite words nobody said.
+
 Conditional clauses ("only when", "only if", "must not ... unless") compile
 into typed `forbid` rules linked by `requires_rule`, not property facts; one
 `kb_model` or `kb_compile_intent` cannot translate stays an `ontology_gap`.
@@ -334,6 +399,8 @@ For each relational clause, call `kb_model` with `mode: "predicates"`, that clau
 reviewed `schemaId`. If `binding_status` is `incomplete`, supply
 `argumentBindings` and retry. Persist `fact_kind: predicate` with the same
 `claim_key` / `claim_text`, then link `REQ -> fact` with `requires_predicate`.
+`claim_key` is derived from `claim_text`, so a ground fact may send the exact
+clause alone and Kibi fills the key in; a sent key must equal the derived one.
 Use `kb_model` with `mode: "requirement"` for strict scalar clauses. Use
 `fact_kind: observation` only for a true ontology gap. The manifest is not
 grounding: run `logic-coverage` so each key binds to one ground fact.
@@ -384,7 +451,17 @@ a second grounding link would fail, so keep the existing link or apply the
 `kb_delete` of the old link, requirement link; between the last two `kb_check`
 reports both `logic-coverage` and `strict-req-fact-pairing` for the
 requirement, as `expected.kbCheckAfterStep` states; run `kb_check` after the
-last step and apply `rollback` if it is not clean); `provide_argument_bindings` and `record_ontology_gap` mean
+last step and apply `rollback` if it is not clean). `keep_existing_grounding`
+means the requirement already links a predicate fact with the candidate's
+`canonical_key` (`existingGrounding[].matchedBy` is `canonical_key` when the
+claim was worded differently), so write nothing. `extend_requirement` means
+the requirement's proposition ledger has no entry for this text, so a link
+cannot be made and no fact is planned: add the clause to the requirement's
+prose (`mode: "requirement"`, or `kb_upsert` with the extended `semantic_text`
+and the ledger `mode: "analyze"` returns) and call `mode: "predicates"` again.
+Read `decisionConflicts` and its warnings whenever `plan` is null: they name
+the stored decision facts the candidate would contradict and the requirements
+that own them. `provide_argument_bindings` and `record_ontology_gap` mean
 the same as for an ungrounded claim, and the gap observation is not a grounding
 link, so write it exactly as returned (tags, `claim_text`, `document.body`, no
 `claim_key`, no relationships). Record an ontology gap only when no returned schema fits the

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

@@ -6,7 +6,7 @@ Requirement prose remains the human-readable source. Facts add queryable semanti
 
 Logical coverage is clause-based, not entity-based. Give `kb_model` (`mode: "analyze"`) the complete requirement body and verify that its `clauses` list contains every atomic obligation. Supply the `clauses` input yourself when automatic splitting would combine or omit obligations. For every normative clause:
 
-- preserve the returned stable key as `claim_key` and the exact clause as `claim_text` on its ground fact;
+- put the exact clause as `claim_text` on its ground fact, with the returned stable key as `claim_key` or none (Kibi derives a missing key; a sent key must match);
 - add the key to the exact current `logic_claims` set, removing only stale keys whose propositions no longer exist in the source;
 - link it through exactly one `requires_property` for `property_value`, one `requires_predicate` for `predicate`, or one `requires_rule` for a safe `rule` fact;
 - leave ambiguity and ontology gaps visibly unresolved—observations do not satisfy `logic-coverage`.
@@ -68,14 +68,16 @@ id: FACT-SUSPENDED-PUBLISH-DENIED
 status: active
 fact_kind: predicate
 predicate_name: permission_rule
-predicate_args: [suspended_user, publish, articles, deny]
+predicate_args: [suspended_user, publish, article, deny]
 polarity: deny
-canonical_key: permission_rule(suspended_user,publish,articles,deny)
+canonical_key: permission_rule(suspended_user,publish,article,deny)
 claim_key: <advisor-issued key for this exact clause>
 claim_text: Suspended users must not publish articles.
 relationship: { type: requires_predicate, from: REQ-SUSPENDED-PUBLISH-DENIED, to: FACT-SUSPENDED-PUBLISH-DENIED }
 ```
 
+Inferred bindings drop the article and singularise the resource (`articles` becomes `article`, `any analysis request` and `analysis requests` both become `analysis_request`), so an allow and a deny on the same actor, action and resource share one key. Grants read the same as `allowed`: `may`, `can`, `is allowed to`, `are permitted to`, `must be able to`, `are able to`, `have permission to` and `are entitled to` all select `permission_rule` with `polarity: assert`.
+
 If another current requirement links an `assert` fact with the same predicate namespace, name, and ordered arguments, `domain-contradictions` reports the pair. More complex semantic conflicts require a shared canonical schema and arguments; do not assume Kibi can prove arbitrary equivalence between differently shaped predicates.
 
 The full logical representation of a requirement is the conjunction of all of its linked ground property and predicate terms. Conditions, exceptions, permissions, and ordering constraints remain explicit arguments of their declared schemas. Contradiction detection therefore depends on equivalent prose reusing the same predicate name, argument roles, ordered canonical values, and opposing polarity rather than inventing synonymous terms.

package/skills/kibi-usage/resources/source-authoring.md

@@ -23,8 +23,10 @@ drift diagnostic. Unresolved Git index conflicts are likewise blocking; Kibi
 never chooses a merge winner.
 
 Relationship upserts and relationship deletes patch only the canonical shard,
-preserving unrelated records. Authored entity deletion returns a hash-bound
-plan; approve that plan through `kb_apply_plan`. Evolve requirements with a new
+preserving unrelated records. Authored entity deletion writes nothing and
+returns a hash-bound plan (`outcome: plan_returned`); approve it by running the
+returned `nextActions[0]` (`kb_apply_plan` with `{plan, approvedPlanHash}`)
+unchanged, or by repeating `kb_delete` with `approvedPlanHash`. Evolve requirements with a new
 requirement and `supersedes`, rather than deleting the old semantic claim.
 
 On `committed_with_repairs`, inspect `effects` and execute the typed required

package/skills/kibi-usage/resources/ui-requirements.md

@@ -126,8 +126,8 @@ diagnostics (`symbol_semantic_review_needed`).
    `requires_predicate`.
 3. Scalar placement/alignment/order clauses: `kb_model` (`mode: "requirement"`), apply the strict
    subject/property plan and `constrains` / `requires_property`.
-4. Preserve `claim_key` / `claim_text`; merge every key into the requirement
-   `logic_claims` manifest.
+4. Preserve `claim_key` / `claim_text` (a missing key is derived from the
+   text); merge every key into the requirement `logic_claims` manifest.
 5. `kb_upsert` with `dryRun: true`, create endpoints first, then sequential `kb_upsert`.
 6. `kb_check` with `logic-coverage`, `predicate-verifiability`, `domain-contradictions`,
    then a final unfiltered `kb_check`.

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

@@ -203,7 +203,7 @@ Optional per-project workflow for recording what the screen should look like. No
 2. Run `kb_model` with `mode: "analyze"` on the description; audit or supply `clauses`.
 3. For relational layout clauses ("X must remain visually aligned with Y"), call `kb_model` with `mode: "predicates"`, apply the returned `fact_kind: predicate` plan with `predicate_name: visual_layout_rule` and `requires_predicate`.
 4. For scalar placement, alignment, and ordering clauses, call `kb_model` with `mode: "requirement"` and apply strict `fact_kind: subject` / `fact_kind: property_value` facts linked with `constrains` / `requires_property`. Model header order as indexed property keys (`nav_order_1`, `nav_order_2`, ...) against one subject region.
-5. Preserve `claim_key` / `claim_text` on every ground fact and merge every key into the requirement `logic_claims` manifest.
+5. Preserve `claim_key` / `claim_text` on every ground fact (a missing `claim_key` is derived from `claim_text`) and merge every key into the requirement `logic_claims` manifest.
 6. Model UI components as `symbol` entities with `sourceFile` and `symbol_role: behavioral`, linked `implements` to the requirement.
 7. `kb_upsert` with `dryRun: true`, create endpoints first, then sequential `kb_upsert`. Run `kb_check` with `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`, then a final unfiltered `kb_check`.