kibi-runtime 1.0.1

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

@@ -0,0 +1,74 @@
+---
+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.0.0
+kibiCompatibility: ">=1.0.0"
+tags:
+  - kibi
+  - mcp
+  - freshness
+  - agent-guidance
+resources:
+  - resources/branch-lifecycle.md
+  - resources/source-authoring.md
+  - resources/operation-access.md
+---
+## Goal
+
+Help agents decide whether Kibi knowledge is current enough to support safe changes while preserving source-file traceability and approved interface boundaries.
+
+## Interface Selection
+
+1. Use whichever approved peer is visible: MCP or the trusted project-local CLI.
+2. They have the same operation semantics and machine envelope; neither is preferred.
+3. If neither surface is available, stop and tell the operator which capability must be enabled.
+4. Never install packages, choose a package manager, or use a global fallback as part of freshness inspection.
+
+Use `kibi-usage/resources/operation-access.md` for exact dedicated routes. A project-local CLI freshness check is executable as:
+
+```bash
+echo '{}' | npx --no-install kibi status --input -
+```
+
+## Capability Workflow
+
+- Use `kb_status`, or `status --input`, first to confirm branch attachment, freshness state, dirty-worktree evidence, and whether the knowledge snapshot is safe to rely on.
+- Treat `branchAttachment.gitBranch`, `branchAttachment.kbBranch`, and
+  `branchAttachment.storePath` as exact identities. Hashed stores require a
+  matching `branch.json`; a `legacy_compat` attachment is read-only until an
+  explicit old/new migration is approved.
+- Inspect bounded `staleReasons` (indexed source missing/newer or documentation
+  source newer) and `verificationSnapshotChanges`. Kibi deliberately reports
+  editor/config paths such as editor dot-directories; do not silently ignore them.
+- Use `kb_query`, or `query --input`, with `sourceFile` and text references for source-linked discovery.
+- Re-run `kb_search`, or `search --input`, after sync gaps or stale context are detected.
+- If knowledge must change, use the selected interface's `kb_upsert`/`upsert` or `kb_delete`/`delete` operation sequentially, then finish with `kb_check`/`check`.
+- If status returns `migrationPlan.version: kibi.migration-plan.v2`, inspect its
+  hash, scope, dependencies, and safety classes. Apply only ready automatic
+  actions with explicit hash/action approval through `kb_apply_plan` or
+  `kibi migrate --apply-safe`; escalate operator actions and never infer a
+  migration from prose suggestions.
+- Parse the outer `kibiProtocol`/`resultVersion` envelope. If a mutation returns
+  `committed_with_repairs`, follow required typed `nextActions`; never retry the
+  original operation.
+
+## Guidance
+
+- Treat MCP and the trusted project-local CLI as equal peer surfaces.
+- Report task outcome separately from KB, verification, proof, and limitation
+  state. A maintenance task can be complete with stale KB state or unresolved
+  proof only when its scoped objective is complete and the status is named
+  accurately; never call the KB clean/fresh in that case.
+- A legacy attachment blocks mutation, and a dirty verification snapshot blocks
+  evidence-dependent closeout. Name the exact paths/symbol IDs and whether the
+  result is fixed, accepted, or deferred.
+- If entities look stale, refresh context through an approved Kibi capability and then re-query.
+- 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.
+- Kibi authors tracked files but never Git-stages or commits them; ordinary Git workflows remain responsible for review and commit.
+- Completion must state one freshness outcome: KB updated, no KB impact with rationale, or deferred/failed.
+
+For exact branch lifecycle, quarantine, restore, and source-first writes, read
+the shared `kibi-usage/resources/branch-lifecycle.md` and
+`source-authoring.md` resources.

package/dist/skills/kibi-freshness/resources/branch-lifecycle.md

@@ -0,0 +1,7 @@
+# Branch lifecycle
+
+Use the exact `KIBI_BRANCH` value or Git symbolic HEAD. Hashed stores carry a
+matching `branch.json`; missing stores are rebuilt from tracked sources by
+`kibi sync`. Legacy literal stores require explicit migration. Kibi never copies
+stores between branches or resolves Git conflicts.
+

package/dist/skills/kibi-freshness/resources/operation-access.md

@@ -0,0 +1,6 @@
+# Operation access
+
+Use visible approved MCP or the trusted project-local CLI. `kb_status`/`status`
+is read-only and returns the shared versioned result envelope with exact branch,
+store, freshness, effects, diagnostics, and typed next actions.
+

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

@@ -0,0 +1,7 @@
+# Source authoring
+
+Tracked documents and relationship shards are authoritative. Kibi may write
+them transactionally but does not stage or commit them. Inspect `effects` and
+typed `nextActions`; after `committed_with_repairs`, repair without retrying the
+original mutation.
+

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

@@ -0,0 +1,60 @@
+---
+id: kibi-traceability
+name: kibi-traceability
+description: Maintain source-first requirement, scenario, test, symbol, and proof traceability through Kibi's peer interfaces.
+version: 2.0.0
+kibiCompatibility: ">=1.0.0"
+tags:
+  - kibi
+  - traceability
+  - source-first
+  - proof
+  - agent-guidance
+resources:
+  - resources/traceability.md
+  - resources/branch-lifecycle.md
+  - resources/source-authoring.md
+  - resources/operation-access.md
+---
+## Goal
+
+Keep product intent connected to implementation without a parallel ticket
+bureaucracy. Requirements own symbols, requirements have clause-complete
+semantics, scenarios have tests, and proof-bearing tests have fresh evidence.
+
+## Interface Selection
+
+Use the visible approved MCP tools or trusted project-local CLI as equal peer
+interfaces. Select the surface by capability; neither is semantically preferred.
+For CLI JSON, use a dedicated route such as
+`printf '%s\n' '{}' | kibi status --input -`.
+
+## Workflow
+
+Use the visible approved MCP tools or trusted project-local CLI as equal peer
+interfaces. Discover with `kb_search`, exact-filter with `kb_query`, and inspect
+`kb_status` before branch-sensitive work. Preserve `REQ-* -> SCEN-* -> TEST-*`;
+link production symbols with `implements` and qualifying tests with
+`executable_for`/`covered_by`.
+
+After source edits, run targeted `kb_check` with impact diagnostics, update
+tracked Markdown/YAML/manifests and canonical relationship shards through
+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.
+
+## Typed recovery and proof
+
+Parse `kibiProtocol`, `resultVersion`, `status`, `effects`, diagnostics, and
+typed `nextActions`. On `committed_with_repairs`, execute the required repair
+action and never retry the original mutation. Keep ontology gaps, ambiguity,
+stale snapshots, unavailable receipts, and incomplete grounding explicit.
+
+Fresh proof requires a current verification snapshot, the exact contracted E2E
+command, an append-only receipt, and current symbol coordinates. Structural
+coverage and a green check are not proof by themselves.

package/dist/skills/kibi-traceability/resources/branch-lifecycle.md

@@ -0,0 +1,7 @@
+# Branch lifecycle
+
+The exact Git ref is the branch identity. Hashed stores are rebuildable
+artifacts, missing stores compile from this checkout, and Git remains the sole
+merge/conflict authority. Explicitly migrate legacy literal stores; do not copy
+another branch's compiled state.
+

package/dist/skills/kibi-traceability/resources/operation-access.md

@@ -0,0 +1,5 @@
+# Operation access
+
+Use the shared operation contracts through approved MCP or the trusted project-local
+CLI. Parse `kibiProtocol`, `resultVersion`, `status`, `effects`, diagnostics,
+and typed `nextActions`; do not retry a mutation after authoritative commit.

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

@@ -0,0 +1,6 @@
+# Source authoring
+
+Use `document.path`/`document.body` for source-first writes. Preserve existing
+body bytes when body is omitted, patch relationship shards without dropping
+unrelated records, and follow typed repair actions after partial completion.
+

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

@@ -0,0 +1,8 @@
+# Traceability detail
+
+Model one requirement clause at a time. Use strict fact lanes for contradiction
+checks, predicate schemas for project ontology, and observation/meta facts for
+bugs and workarounds. Query all relationship endpoints before writing; a graph
+link is not proof until the scenario, test, symbol, and fresh receipt are
+readable at the current snapshot.
+

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

@@ -0,0 +1,152 @@
+---
+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.1.0
+kibiCompatibility: ">=1.0.0"
+tags:
+  - kibi
+  - mcp
+  - cli
+  - source-first
+  - branching
+  - traceability
+  - recovery
+resources:
+  - resources/operation-access.md
+  - resources/branch-lifecycle.md
+  - resources/source-authoring.md
+  - resources/relationship-directions.md
+  - resources/fact-lanes.md
+  - resources/workflows.md
+  - resources/ui-requirements.md
+  - resources/logic-ir.md
+  - resources/kb-improvement.md
+---
+# Kibi Usage
+
+Consult this skill before any Kibi knowledge base operation, on first
+interaction with a Kibi-enabled repo, after stale or dirty status is suspected,
+and before mutations.
+
+Kibi is an agent-native requirements compiler. Use it to retain product intent,
+compile branch-local requirements and scenarios, link symbols to ownership,
+and prove implementation with fresh evidence.
+
+## Interface Selection
+
+Use whichever capability is visible and approved. The surfaces are equal peers:
+
+1. If approved Kibi MCP tools are visible, use them.
+2. Otherwise use `npx --no-install kibi ...` from the trusted project-local CLI.
+3. If the operator capability is unavailable or too old for the needed route,
+   stop and identify the missing capability.
+4. Never use a global fallback, an installing runner, or an unapproved route.
+
+Hosts may expose prefixed identifiers such as `kibi_kb_search`,
+`kibi_kb_query`, and `kibi_kb_upsert`; map them to the canonical MCP names.
+
+The CLI JSON route accepts the same business object as MCP:
+
+```bash
+printf '%s\n' '{"query":"checkout","limit":10}' | npx --no-install kibi search --input -
+```
+
+Read `resources/operation-access.md` for the route, result version, effects,
+mutability, and Prolog requirements of each operation.
+
+## Safe workflow
+
+1. Always discover before you mutate: start with `kb_search`, then exact-filter with `kb_query`. Use
+   `kb_status` when branch or freshness confidence matters.
+2. Resolve genuine ambiguity with the human; use semantic advisor/modeling
+   operations for deterministic interpretation and typed facts.
+3. Create endpoints before relationships and upsert small batches sequentially.
+   Keep the canonical `REQ-* -> SCEN-* -> TEST-*` chain.
+4. Author tracked Markdown/YAML/manifests and relationship shards through Kibi;
+   Kibi never Git-stages or commits those files. Do not read or edit `.kb`
+   directly.
+5. Finish with targeted and final `kb_check`, then read status/coverage and
+   state freshness, verification, proof, and limitations separately.
+
+Run `kb_check` with specific rules during iteration and the unfiltered final
+check. Never fire `kb_upsert` calls in parallel; create or confirm endpoint
+entities before linking them. The canonical MCP names are `kb_search`,
+`kb_query`, `kb_upsert`, and `kb_check`.
+
+## Exact Git attachment
+
+The active ref is the exact KB identity. `KIBI_BRANCH` is used verbatim; Git's
+symbolic HEAD is used otherwise. Slash, `@`, Unicode, `main`, `master`, and
+detached states are not normalized or merged. Hashed stores and their
+`branch.json` identity fence are compiled artifacts. A missing exact store is
+created by `kibi sync` from this checkout's tracked sources. Kibi never copies
+stores across branches and never selects merge winners; unresolved authored Git
+conflicts block compilation. See `resources/branch-lifecycle.md` for legacy
+migration, worktrees, quarantine, restore, and purge.
+
+## Typed results and recovery
+
+Every CLI JSON/MCP result has `kibiProtocol`, `operation`, `resultVersion`,
+`status`, `data`, `effects`, `diagnostics`, and typed `nextActions`. Treat
+`status: error` as a failed pre-commit operation. 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
+diagnostic telemetry.
+
+## Source-first mutation
+
+Use `document.path` when a new entity has no single configured writable target.
+Existing entities preserve body bytes when `document.body` is omitted; new
+requirements default their body to `semantic_text`. Relationship mutations
+patch canonical shards while preserving unrelated records. Authored entity
+deletion returns a hash-bound approval plan; requirements normally evolve via a
+new entity linked with `supersedes`. Read `resources/source-authoring.md` before
+source writes, deletion approval, or recovery.
+
+## Semantic and proof guardrails
+
+Prolog proves only encoded facts. Keep ambiguity, ontology gaps, incomplete
+grounding, stale snapshots, and failed or unavailable evidence explicit. Use
+`fact_kind: subject` plus `property_value`/`predicate` lanes for contradiction-
+safe normative claims; use `observation` or `meta` for bug/workaround notes and
+`flag` only for actual runtime/config gates. Requirements require scenarios,
+tests, symbol ownership, and fresh proof-bearing receipts before claiming proof.
+For an existing product KB that needs semantic backfill, read
+`resources/kb-improvement.md`.
+
+## Predicate Ontology Decision Tree
+
+Call `kb_semantic_advisor`, `kb_model_requirement`, or `kb_suggest_predicates`
+before encoding a normative clause. Use `fact_kind: predicate` with
+`requires_predicate` when a suitable schema exists; use `fact_kind: observation`
+for an ontology gap. Keep the `REQ -> TEST` chain and use `verified_by` for
+proof-bearing links. Relationship direction is fixed, and every `from` in a
+relationship batch must equal the upserted entity ID.
+
+## Symbol-First Traceability
+
+Represent implementation ownership with a `symbol` entity and an `implements`
+relationship from the symbol to the requirement. Do not rely on legacy
+`// implements REQ-xxx` comments as the traceability record.
+
+## Complete Logical Coverage
+
+Decompose all atomic normative clauses into `claim_key`/`claim_text` entries in
+`logic_claims`; human or agent review still confirms that the atomic clauses
+exhaust the prose. Run `logic-coverage` and `domain-contradictions` after
+modeling. Use `status: implemented` only as historical input; use a valid status
+such as `closed`, add an `implemented` tag, and link evidence instead.
+
+## Anti-Patterns and Remediation
+
+Reject reversed relationship direction, a Bug-as-flag record without a runtime
+gate, direct KB-store edits, and a generic `strict kb_upsert.properties` field.
+Keep symbol payloads minimal. When a generic `Query failed` appears, do not keep
+retrying the same payload; inspect the typed error and `nextActions`.
+
+Kibi may now author tracked Markdown/YAML evidence transactionally. The former
+statement “Kibi operation writes do not automatically stage markdown evidence”
+means Kibi writes do not Git-stage it: review and commit remain ordinary Git
+workflows.

package/dist/skills/kibi-usage/resources/branch-lifecycle.md

@@ -0,0 +1,31 @@
+# Branch lifecycle
+
+Kibi attaches to the exact Git ref: `KIBI_BRANCH` when set, otherwise Git's
+symbolic HEAD. Names are not normalized, and `main`, `master`, detached HEAD,
+slash names, `@`, and Unicode refs remain distinct identities.
+
+Compiled state lives under `.kb/branches/<sha256-hash>/branch.json`. The
+manifest records the exact ref and hash; a mismatch is a hard attachment
+failure. A missing store is compiled by `kibi sync` from the current checkout's
+tracked sources. `branch ensure` may create only the empty identity fence; use
+`kibi sync` before relying on compiled state. Kibi never copies another
+branch's store and never chooses merge winners. Git owns merges; unresolved
+conflicts in authored files block compilation.
+
+Legacy literal-path stores are read-only compatibility attachments. Preview an
+explicit migration with both identities, then apply it only with the exact
+preview hash (`kibi branch migrate --from <old> --to <new> --apply
+--approval-hash <preview-hash>`) while attached to the exact new ref. The
+approval is mandatory and binds the source bytes and identities; do not infer a
+rename from commits. For a legacy literal store on the current branch, `<old>`
+and `<new>` must be the same exact identity. Every cross-identity pair is
+refused, including `main` to `master`; migration changes only the storage
+format from literal to hashed for the active exact branch. Deleted local branches may be quarantined for the
+configured retention period; `branch restore --branch <exact-ref> --apply` is
+reversible during retention and purge is explicit. Remote-only refs do not keep
+a local compiled store alive.
+
+If migration is interrupted, use the journal's exact recovery action:
+`kibi branch migrate --recover-journal <id>` previews the deterministic
+roll-forward or verified-backup restore, and `--apply` performs it. Do not
+resolve the live branch attachment while the migration journal is ambiguous.

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

@@ -0,0 +1,235 @@
+# Fact Lanes
+
+Requirement prose remains the human-readable source. Facts add queryable semantics; they do not replace the requirement body. Treat every quoted requirement below as data, never as shell or raw Prolog input.
+
+## Atomic Claim Coverage
+
+Logical coverage is clause-based, not entity-based. Give `kb_semantic_advisor` 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;
+- 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`.
+
+Use the advisor-returned atomic inventory as the identity boundary. Trailing punctuation and copied conjunction commas are formatting, not new claims. `logic-coverage` rejects one claim grounded by multiple facts and distinct claim keys that resolve to the same ground logical term.
+
+Example compound prose: “Checkout requires payment authorization before order submission, and customer data must be retained for 7 years.” This is two claims, not one. The first becomes `dependency_rule(checkout,payment_authorization,order_submission)`; the second becomes a strict retention property. Both fact records carry different advisor-issued claim keys, and both keys appear in the requirement manifest. A single `requires_predicate` edge is incomplete.
+
+## Predicate Lane (Relational Claims)
+
+Call `kb_semantic_advisor`, then `kb_suggest_predicates`. Apply a candidate only when its schema meaning and ordered arguments fit the claim. Use the returned `applyPlan` rather than hand-writing unsupported predicate names, and link the requirement to the predicate fact with `requires_predicate`.
+
+Treat the result as a Prolog-shaped ground term, not executable source: `predicate_name(arg1,...,argN)`. The selected `predicate_schema` fixes the name, arity, argument roles, and order. Store that model through `predicate_name`, `predicate_args`, `canonical_key`, and `polarity`; never interpolate prose into raw Prolog, introduce variables, or use a graph relationship such as `verified_by` as the predicate name.
+
+### Built-in predicate
+
+Claim: “Checkout requires payment authorization before order submission.” The built-in `dependency_rule(subject, prerequisite, dependent)` schema produces:
+
+```yaml
+id: FACT-CHECKOUT-PAYMENT-DEPENDENCY
+status: active
+fact_kind: predicate
+predicate_name: dependency_rule
+predicate_args: [checkout, payment_authorization, order_submission]
+polarity: assert
+canonical_key: dependency_rule(checkout,payment_authorization,order_submission)
+claim_key: <advisor-issued key for this exact clause>
+claim_text: Checkout requires payment authorization before order submission.
+relationship: { type: requires_predicate, from: REQ-CHECKOUT-SUBMISSION, to: FACT-CHECKOUT-PAYMENT-DEPENDENCY }
+```
+
+### Project-local predicate
+
+If the project has an approved `commit_action(subject, trigger, object)` predicate schema, “Editor annotation drafts autosave on navigation” may use:
+
+```yaml
+id: FACT-EDITOR-DRAFT-AUTOSAVE
+status: active
+fact_kind: predicate
+predicate_name: commit_action
+predicate_args: [editor.annotation, navigation, draft]
+polarity: assert
+canonical_key: commit_action(editor.annotation,navigation,draft)
+relationship: { type: requires_predicate, from: REQ-EDITOR-DRAFT-AUTOSAVE, to: FACT-EDITOR-DRAFT-AUTOSAVE }
+```
+
+The project-local schema endpoint must exist before this fact is linked. When ontology extension is explicitly authorized, define it first with `fact_kind: predicate_schema`, `predicate_name`, `predicate_arity`, and equally sized `argument_names` and `argument_types`. Without an authorized stable signature, record `review:ontology-gap` instead of inventing a schema.
+
+### Deny predicate
+
+Claim: “Suspended users must not publish articles.” When `permission_rule` fits, preserve its positive schema name and encode prohibition as polarity:
+
+```yaml
+id: FACT-SUSPENDED-PUBLISH-DENIED
+status: active
+fact_kind: predicate
+predicate_name: permission_rule
+predicate_args: [suspended_user, publish, article]
+polarity: deny
+canonical_key: permission_rule(suspended_user,publish,article)
+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 }
+```
+
+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.
+
+### Lane gates before a predicate lookup
+
+Treat the advisor's proposition status as a hard routing decision. `nonlogical`/`subjective` prose is not a logical claim: keep it as one observation when needed and do not add its key to `logic_claims`. `ambiguous` prose stays an ambiguity observation. `ontology_gap` prose stays unresolved unless an approved schema or validated Logic IR is available. Never split a subjective or commentary sentence into synthetic clauses just because it contains conditional words or domain vocabulary.
+
+If authorized input supplies `projectLocalSchemas`, use those signatures as the authority. Create the minimal `predicate_schema` endpoint before lookup, then rerun `kb_suggest_predicates` on the complete relation if the first lookup had no candidate. Apply exactly one ground predicate and one claim key for that relation. For `must not`, `never`, `cannot`, or `forbidden` wording, preserve the positive schema and set `polarity: deny`; do not turn the result into an asserted predicate or invent a negative name. An empty lookup before the declared schema exists is a retry condition, not proof of an ontology gap.
+
+## Typed rule lane
+
+Use a validated `kibi.logic.v1` object for a proposition whose meaning includes a condition, exception, obligation, prohibition, permission, quantifier, cardinality bound, or bounded temporal relation. `kb_model_requirement` returns the `rule_schema` and `rule` facts plus a `requires_rule` edge. The rule stores canonical JSON and a deterministic hash; any rendered Prolog is an audit view and is never executed. Reject raw goals, function symbols, cuts, meta-calls, dynamic predicates, I/O, unsafe variables, unstratified negation, and unbounded aggregation. Keep the exact proposition in `claim_text`, its advisor key in `claim_key`, and its byte span in the semantic ledger. Run `rule-safety` and `rule-verifiability` before treating the rule as modeled.
+
+### Strict scalar
+
+Claim: “Sessions expire after at most 30 minutes.” This is a scalar limit, not a predicate. Route it through `kb_model_requirement` to a subject plus `property_value` with `operator: lte`, `value_type: int`, and `value_int: 30`, linked by `constrains` and `requires_property`.
+
+### Ambiguous claim
+
+Claim: “Premium accounts get better support.” “Better” does not identify a stable relation or scalar. Keep readable prose and create a `fact_kind: observation` tagged `review:ambiguity`; request clarification before adding strict or predicate facts.
+
+### False-positive trap
+
+Claim: “Suspended users must not publish articles.” A lexical match such as `publishes_event` is semantically wrong because an article is not a domain event. Reject that candidate and use the suitable permission schema if one is returned; otherwise use a review observation. Candidate rank alone is never proof of suitability.
+
+### Ontology gap
+
+Claim: “Annotations remain anchored to selected text after edits.” If no returned built-in or approved project-local schema expresses anchoring preservation, do not invent one:
+
+```yaml
+id: FACT-ONTOLOGY-GAP-ANNOTATION-ANCHOR
+status: active
+fact_kind: observation
+tags: [review:ontology-gap]
+text_ref: docs/requirements/annotation-anchor.md
+```
+
+An ontology-gap observation records review work; it does not make the requirement machine-checkable.
+
+## Strict Lane (Contradiction-Safe)
+
+### fact_kind: subject
+```yaml
+id: FACT-USER-ROLE
+title: User Role Assignment
+status: active
+fact_kind: subject
+subject_key: user.role_assignment
+```
+
+### fact_kind: property_value
+```yaml
+id: FACT-LIMIT-3
+title: Maximum of Three Roles
+status: active
+fact_kind: property_value
+subject_key: user.role_assignment
+property_key: max_roles
+operator: lte
+value_type: int
+value_int: 3
+```
+
+## Granular Facts for Coherence Checks
+
+Granular strict facts work best when each `property_value` represents one semantic claim about one `subject_key` and one `property_key`. This lets `domain-contradictions` compare current requirements that constrain the same subject and require incompatible values.
+
+### Role set conflict
+
+`REQ-ROLE-SET-2` and `REQ-ROLE-SET-3` are incoherent if both are current: they each define the exact allowed role set, but one allows two roles and the other allows three. Encode compact set values as canonical strings because the strict property schema supports string, int, number, and bool values.
+
+```yaml
+subject:
+  id: FACT-USER-ROLES
+  title: User roles
+  status: active
+  fact_kind: subject
+  subject_key: user.roles
+
+property_values:
+  - id: FACT-USER-ROLES-ALLOWED-2
+    title: User and admin roles only
+    status: active
+    fact_kind: property_value
+    subject_key: user.roles
+    property_key: user.roles.allowed_set
+    operator: eq
+    value_type: string
+    value_string: user,admin
+  - id: FACT-USER-ROLES-ALLOWED-3
+    title: User, admin, and superadmin roles
+    status: active
+    fact_kind: property_value
+    subject_key: user.roles
+    property_key: user.roles.allowed_set
+    operator: eq
+    value_type: string
+    value_string: user,admin,superadmin
+
+relationships:
+  - { type: constrains, from: REQ-ROLE-SET-2, to: FACT-USER-ROLES }
+  - { type: requires_property, from: REQ-ROLE-SET-2, to: FACT-USER-ROLES-ALLOWED-2 }
+  - { type: constrains, from: REQ-ROLE-SET-3, to: FACT-USER-ROLES }
+  - { type: requires_property, from: REQ-ROLE-SET-3, to: FACT-USER-ROLES-ALLOWED-3 }
+```
+
+### Permission actor conflict
+
+`REQ-ADMIN-CAN-MANAGE-BILLING` and `REQ-ONLY-SUPERADMIN-MANAGES-BILLING` conflict when both define the exact allowed actor for the same permission.
+
+```yaml
+subject:
+  id: FACT-BILLING-MANAGE
+  title: Billing management permission
+  status: active
+  fact_kind: subject
+  subject_key: billing.manage
+
+property_values:
+  - id: FACT-BILLING-MANAGE-ACTOR-ADMIN
+    title: Admin can manage billing
+    status: active
+    fact_kind: property_value
+    subject_key: billing.manage
+    property_key: billing.manage.allowed_actor
+    operator: eq
+    value_type: string
+    value_string: admin
+  - id: FACT-BILLING-MANAGE-ACTOR-SUPERADMIN
+    title: Only superadmin can manage billing
+    status: active
+    fact_kind: property_value
+    subject_key: billing.manage
+    property_key: billing.manage.allowed_actor
+    operator: eq
+    value_type: string
+    value_string: superadmin
+```
+
+When a contradiction is intentional evolution rather than a real conflict, link the replaced requirement to the replacement requirement with `supersedes`.
+
+## Context Lane (Non-Blocking)
+
+### fact_kind: observation
+For bug records, incident notes, and observed behavior.
+```yaml
+id: FACT-BUG-123
+title: Login fails on Safari 17
+status: active
+fact_kind: observation
+```
+
+### fact_kind: meta
+For governance notes, process commentary, and workaround documentation.
+```yaml
+id: FACT-WORKAROUND-456
+title: Temporary cache bypass for v2 migration
+status: active
+fact_kind: meta
+```

package/dist/skills/kibi-usage/resources/kb-improvement.md

@@ -0,0 +1,38 @@
+# Existing Product KB Improvement
+
+Use this resource when an existing product KB already has REQ → SCEN → TEST →
+symbol traceability and the task is to add typed facts so normative claims are
+queryable and contradiction-checkable.
+
+Keep the original requirement prose readable. Facts add semantics; they do not
+replace the requirement body. Lane choice, field names, and predicate routing
+are in `resources/fact-lanes.md` and the Predicate-First workflow in
+`resources/workflows.md`.
+
+## Claim routing
+
+| Claim type | Model as | Relationship |
+| --- | --- | --- |
+| Measurable normative property | `subject` + `property_value` | `constrains` + `requires_property` |
+| Domain invariant or behavior relation | `predicate` | `requires_predicate` |
+| Bug, workaround, or observed evidence | `observation` | usually `relates_to` |
+| Process or governance note | `meta` | usually `relates_to` |
+| Runtime or config gate | `flag` | `guards` |
+
+Call `kb_semantic_advisor` on the complete requirement body before encoding a
+clause. Apply a predicate only when a returned schema fits; otherwise leave an
+ontology-gap observation.
+
+## Source and RDF reconciliation
+
+After each approved write:
+
+1. Query the exact fact IDs.
+2. Confirm `fact_kind`, `predicate_name` or `property_key`, and `canonical_key`
+   appear through Kibi tools, not only in authored Markdown.
+3. Graph from the requirement with `requires_predicate` and `requires_property`.
+4. If Markdown has predicate or property fields but queries do not, report a
+   sync or import issue before creating duplicates.
+
+Treat active tool query results as operational truth. Authored Markdown is
+evidence of intent, not proof of active KB state.