kibi-cli 0.14.0 → 0.16.1

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

@@ -2,7 +2,7 @@
 id: kibi-usage
 name: Kibi Usage
 description: Guides agents to use Kibi MCP, facts, relationships, and validation correctly
-version: 1.0.0
+version: 1.2.0
 kibiCompatibility: ">=0.11.0"
 tags:
   - kibi
@@ -14,29 +14,52 @@ resources:
   - resources/relationship-directions.md
   - resources/fact-lanes.md
   - resources/workflows.md
+  - resources/operation-access.md
 ---
-
 # Kibi Usage
 
-Consult this skill before any Kibi knowledge base operation, on first interaction with a Kibi-enabled repo, after detecting stale or dirty KB status, and before performing mutations.
+Consult this skill before any Kibi knowledge base operation, on first interaction with a Kibi-enabled repo, after stale or dirty KB status is suspected, and before mutations.
+
+## Interface Selection
+
+Use this order for every Kibi operation:
+
+1. If Kibi MCP tools are visible and approved in the current environment, use MCP.
+2. Otherwise, in a trusted workspace, use the project-local CLI through a non-installing runner: `npx --no-install kibi ...` or `bunx --no-install kibi ...`.
+3. If the project-local CLI is unavailable or too old for the needed route, stop and tell the operator to enable or install Kibi.
+4. Never use a global fallback or an installing runner. Never probe or install packages as a side effect of interface selection.
+
+Use exact MCP tool names, dedicated CLI routes, input modes, effects, and Prolog requirements from `resources/operation-access.md`. Do not invent a generic operation runner. Do not read or edit files inside `.kb/` directly.
+
+CLI JSON mode accepts MCP-shaped business input at `--input <file|->`.
+
+```bash
+echo '{"type":"req","id":"REQ-001","properties":{"title":"Test","status":"open"}}' | npx --no-install kibi upsert --input -
+```
+
+```bash
+echo '{"query":"authentication","limit":10}' | bunx --no-install kibi search --input -
+```
 
-## MCP-Only Rules
+## MCP Tool Names
 
-Interact with the knowledge base exclusively through MCP tools. Do not read or edit files inside `.kb/` directly. Do not run any `kibi` CLI commands from the agent session. The MCP surface is the only sanctioned interface for agents.
+Kibi canonical MCP names include `kb_search`, `kb_query`, `kb_upsert`, `kb_check`, `kb_status`, `kb_validate_upsert`, and related `kb_*` tools. OpenCode may expose prefixed identifiers such as `kibi_kb_search`, `kibi_kb_query`, and `kibi_kb_upsert`. Use the visible Kibi MCP tool identifiers and map them back to canonical operations before reasoning about behavior.
 
-### Tool Name Prefixes
+## Discovery First
 
-Kibi's canonical MCP names are `kb_search`, `kb_query`, `kb_upsert`, `kb_check`, and related `kb_*` tools. Some hosts add a server prefix when exposing tools to agents. In OpenCode, use the visible `kibi_kb_search`, `kibi_kb_query`, `kibi_kb_upsert`, and `kibi_kb_check` names when exact tool identifiers are required; they map to the same canonical MCP names.
+Always discover before you mutate. Start exploratory work with `kb_search` across metadata and markdown body text. Split broad queries into one to three focused probes and review top hits before concluding knowledge is absent.
 
-## Discovery-First Workflow
+Use `kb_query` for exact lookups by `id`, `type`, `tags`, or `sourceFile`. Use `kb_status` when branch attachment, freshness, or stale context could affect the decision. Mutate only after discovery confirms the target state.
 
-Always discover before you mutate. Start with `kb_search` for exploratory discovery across metadata and markdown body text. Split broad queries into 1-3 focused probes. Review top hits for relevance before concluding the KB lacks knowledge.
+## Approval Boundaries
 
-Follow up with `kb_query` for exact lookups by `id`, `type`, `tags`, or `sourceFile`. Call `kb_status` to inspect branch attachment and freshness when stale context would affect decisions. Only after discovery and confirmation should you mutate.
+Do not perform Kibi mutations unless the current task calls for knowledge-base changes or the user explicitly asks for them. Discovery and validation are acceptable when needed to understand impact, freshness, traceability, or existing requirements.
+
+Kibi guidance does not define a repository's package manager, branch names, release scripts, or publishing workflow. Follow the repository's own instructions for those concerns. Never use Kibi interface selection to install packages, change dependency manifests, or bypass sandbox and approval boundaries.
 
 ## Relationship Directions
 
-Relationship direction is fixed and semantic. Getting it wrong breaks traceability queries and validation.
+Relationship direction is fixed and semantic. Reversed links break traceability queries and validation.
 
 | Relationship | Direction | Meaning |
 |-------------|-----------|---------|
@@ -47,23 +70,29 @@ Relationship direction is fixed and semantic. Getting it wrong breaks traceabili
 | `executable_for` | symbol -> test | Symbol is executable test code for a test entity |
 | `constrains` | req -> fact(subject) | Requirement constrains a domain fact |
 | `requires_property` | req -> fact(property_value) | Requirement requires a property value |
+| `requires_predicate` | req -> fact(predicate) | Requirement requires a ground ontology predicate |
 | `supersedes` | old-req -> new-req | Old requirement is replaced by new requirement |
 | `covered_by` | symbol -> test | Production symbol has coverage evidence from a test |
 
-See `resources/relationship-directions.md` for detailed payload examples.
+Before/after for reversed direction:
+
+- Wrong: `relationships: [{ type: "implements", from: "REQ-001", to: "SYM-001" }]`
+- Right: `relationships: [{ type: "implements", from: "SYM-001", to: "REQ-001" }]`
 
 ## Symbol-First Traceability
 
-Trace code through `symbol` entities, not inline legacy comments. Do not use legacy `// implements REQ-xxx` comments as the primary marker for new or modified code. If a symbol is new or its requirement ownership changes, create or update the `symbol` entity and add an `implements` relationship from the symbol to the requirement.
+Preserve source-file traceability whenever creating or updating requirements, facts, scenarios, tests, or symbols. Prefer durable `sourceFile` references and symbol coordinates that point to tracked repository files. For code ownership, create or update a `symbol` entity and add an `implements` relationship from the symbol to the requirement; link symbols to tests with `covered_by` when coverage evidence is needed.
 
-Use comments only as a temporary backward-compatibility fallback when the symbol manifest cannot be updated in the same task. Prefer durable symbol coordinates in `documentation/symbols.yaml` and `documentation/symbol-coordinates.yaml`, then link those symbols through MCP relationships.
+Do not use legacy `// implements REQ-xxx` comments as the primary marker for new or modified code. Use comments only as a temporary compatibility fallback when symbol metadata cannot be updated in the same task.
+
+Preferred traceability model:
 
 ```yaml
-# Preferred traceability model
 symbol:
   id: SYM-admin-billing-policy
   title: Admin billing policy check
   status: active
+  sourceFile: src/admin/billing.ts
 relationships:
   - type: implements
     from: SYM-admin-billing-policy
@@ -75,17 +104,13 @@ relationships:
 Normative requirements that must participate in contradiction blocking use the strict fact lane. Create a `fact_kind: subject` fact and link it from the requirement via `constrains`. Create a `fact_kind: property_value` fact and link it via `requires_property`.
 
 ```yaml
-# Fact entity
 id: FACT-USER-ROLE
-title: User Role Assignment
-status: active
 fact_kind: subject
 subject_key: user.role_assignment
+```
 
-# Requirement entity
+```yaml
 id: REQ-019
-title: Users can have up to 3 roles
-status: open
 relationships:
   - type: constrains
     from: REQ-019
@@ -95,112 +120,110 @@ relationships:
     to: FACT-LIMIT-3
 ```
 
-See `resources/fact-lanes.md` for the full strict vs observation lane comparison.
+Model one semantic claim per strict `property_value` fact. Reusing the same `subject_key` and `property_key` lets `domain-contradictions` compare requirements mechanically. If a new requirement intentionally changes a value, create a replacement requirement and link the old requirement to the new one with `supersedes` instead of leaving two current contradictory requirements.
+
+Use `kb_model_requirement` for automated strict-fact modeling when available. It generates subject and property_value facts, links them with `constrains` and `requires_property`, and handles low-confidence downgrades to observation facts automatically.
 
-### Granular fact examples for coherence checks
+Granular fact examples for coherence checks include `REQ-ROLE-SET-2` versus `REQ-ROLE-SET-3` on `user.roles.allowed_set` (`user,admin` versus `user,admin,superadmin`) and `REQ-ADMIN-CAN-MANAGE-BILLING` versus `REQ-ONLY-SUPERADMIN-MANAGES-BILLING` on `billing.manage.allowed_actor`. See `resources/fact-lanes.md`; `domain-contradictions` uses these canonical keys.
 
-Model one semantic claim per strict `property_value` fact. Reusing the same `subject_key` and `property_key` lets `domain-contradictions` compare requirements mechanically.
+## Complete Logical Coverage
 
-Incoherent role-set example: `REQ-ROLE-SET-2` says the allowed user roles are exactly `user,admin`, while `REQ-ROLE-SET-3` says the same property is exactly `user,admin,superadmin`. Both constrain `FACT-USER-ROLES` and require different values for `user.roles.allowed_set`, so they cannot both be current.
+Readable prose is not evidence that a requirement is machine-checkable. Before treating a normative requirement as modeled, decompose its entire body into atomic normative clauses and ground every clause. One correct fact or relationship never proves that the other prose is covered.
+
+1. Call `kb_semantic_advisor` with the complete requirement prose. When the automatic split is incomplete or a sentence contains multiple obligations, pass an explicit `clauses` array containing every atomic normative clause.
+2. Use the stable `claim_key` returned for each clause. Every ground `property_value` or `predicate` fact must preserve that key in `claim_key` and preserve the clause in `claim_text`. Use the advisor-returned inventory exactly; do not add punctuation or wording variants of an existing clause.
+3. Put the complete set of keys in the requirement's `logic_claims` manifest. Merge returned keys with existing values; never overwrite earlier claims while modeling a later clause.
+4. Ground each key through exactly one suitable logical lane: `requires_property` to one strict `property_value` fact, or `requires_predicate` to one ground `predicate` fact. A subject fact supports a strict claim but does not ground a key by itself. Observation, meta, ambiguity, and ontology-gap facts explicitly remain unresolved and do not count as logical coverage.
+5. Run `kb_check` with `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`. `logic-coverage` enforces a one-claim/one-ground-fact mapping and rejects distinct claim keys that encode the same logical term; human or agent review still confirms that the atomic clauses exhaust the prose and that each ground term preserves its meaning.
+
+Kibi emits a non-blocking logical-coverage debt diagnostic for every current requirement without a manifest, independent of title wording. The `logic-coverage` rule is enabled by default for requirements that do declare manifests, so an unfiltered final check catches missing or orphaned ground claims while legacy requirements remain explicit backfill work.
+
+A complete `logic_claims` manifest alone is not a complete model. Semantic-advisor readiness remains partial until the payload has at least one distinct `requires_property` or `requires_predicate` grounding slot per normative claim. This count prevents one token edge from suppressing the remaining plans; only `logic-coverage` readback proves that each slot reaches the fact with the matching claim key.
+
+Never invent, reuse across different clauses, or manually alter a claim key. Kibi derives it from `claim_text` and rejects mismatched mutation and Markdown inputs.
+
+For a compound requirement, the manifest and linked facts form a clause-completeness contract:
 
 ```yaml
-subject:
-  id: FACT-USER-ROLES
-  fact_kind: subject
-  subject_key: user.roles
-
-property_values:
-  - id: FACT-USER-ROLES-ALLOWED-2
-    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
-    fact_kind: property_value
-    subject_key: user.roles
-    property_key: user.roles.allowed_set
-    operator: eq
-    value_type: string
-    value_string: user,admin,superadmin
-
-requirements:
-  - id: REQ-ROLE-SET-2
-    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 }
-  - id: REQ-ROLE-SET-3
-    relationships:
-      - { 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 }
+requirement:
+  id: REQ-CHECKOUT-RETENTION
+  logic_claims: [CLAIM-A1B2C3D4E5F60718, CLAIM-18273645AABBCCDD]
+facts:
+  - fact_kind: predicate
+    claim_key: CLAIM-A1B2C3D4E5F60718
+    claim_text: Checkout requires payment authorization before submission.
+  - fact_kind: property_value
+    claim_key: CLAIM-18273645AABBCCDD
+    claim_text: Customer data must be retained for 7 years.
 ```
 
-Incoherent permission example: `REQ-ADMIN-CAN-MANAGE-BILLING` says `admin` can manage billing, while `REQ-ONLY-SUPERADMIN-MANAGES-BILLING` says the only allowed actor is `superadmin`. Model both against `billing.manage.allowed_actor` with `operator: eq` so the conflict is explicit.
+The example keys are illustrative; use only keys returned for the exact clause text.
+
+## Predicate Ontology Decision Tree
+
+Preserve the readable requirement prose. Facts add a machine-queryable model; they do not replace prose, and stored predicate facts are data queried by Kibi's Prolog layer rather than executable Prolog supplied by the agent.
+
+1. Call `kb_semantic_advisor` on the complete prose, verify its atomic clause inventory, and choose one lane per clause.
+2. For each relational clause, call `kb_suggest_predicates` with that clause and the current `existingLogicClaims`. Read each candidate as a Prolog-shaped ground term `predicate_name(arg1,...,argN)`: the schema fixes the predicate name, arity, argument roles, and argument order.
+3. Accept a candidate only when its meaning and every ordered argument fit the prose. Use the returned `applyPlan`, including its exact `predicate_name`, `predicate_args`, `canonical_key`, and `polarity`; never invent a predicate name, reorder arguments, add variables, or write a raw Prolog clause.
+4. Create or confirm the requirement and `fact_kind: predicate` endpoints, preserve `claim_key` and `claim_text`, merge the returned `logicClaims` into the requirement, then link requirement -> predicate fact with `requires_predicate`. Treat the requirement's logical representation as the conjunction of every linked ground term. Encode a prohibition with `polarity: deny` on the fitting positive schema, not a made-up negative predicate. An `assert` and `deny` requirement over the same namespace, name, and ordered arguments are a blocking `domain-contradictions` conflict, so requirements must reuse the same canonical schema and argument vocabulary for equivalent domain claims.
+5. Use an existing built-in or project-local `fact_kind: predicate_schema`. Create a new schema only when the task explicitly authorizes ontology extension and supplies a stable name, arity, `argument_names`, and `argument_types`; otherwise record `fact_kind: observation` with `review:ontology-gap`.
+6. For each scalar, threshold, duration, boolean, enum-set, or cardinality clause, use `kb_model_requirement` with the current `existingLogicClaims` and the strict subject/property lane instead. For ambiguity or a lexical false positive, preserve the prose as a review observation and report the requirement as logically incomplete.
+7. Validate every payload, create endpoints first, apply `kb_upsert` calls sequentially, read back all affected IDs, and run targeted `logic-coverage`, `predicate-verifiability`, and `domain-contradictions` checks before the final unfiltered `kb_check`. Exact query output can return an array when one relationship type has multiple targets; verify every target rather than reading only one edge.
+
+Example: “Checkout requires payment authorization before order submission” fits `dependency_rule(subject, prerequisite, dependent)`. The ground model is `dependency_rule(checkout,payment_authorization,order_submission)`, stored as:
 
 ```yaml
-property_values:
-  - id: FACT-BILLING-MANAGE-ACTOR-ADMIN
-    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
-    fact_kind: property_value
-    subject_key: billing.manage
-    property_key: billing.manage.allowed_actor
-    operator: eq
-    value_type: string
-    value_string: superadmin
+fact_kind: predicate
+predicate_name: dependency_rule
+predicate_args: [checkout, payment_authorization, order_submission]
+canonical_key: dependency_rule(checkout,payment_authorization,order_submission)
+polarity: assert
+claim_key: <claim key returned by kb_semantic_advisor>
+claim_text: Checkout requires payment authorization before order submission.
 ```
 
-If a new requirement intentionally changes a value, create a replacement requirement and link the old requirement to the new one with `supersedes` instead of leaving two current contradictory requirements.
+Link the requirement to that predicate fact with `requires_predicate`. Do not use `verified_by`, `requires_predicate`, or another relationship type as the `predicate_name`; graph relationships and ontology predicates are different layers.
 
-## Fact vs Flag
+Detailed built-in, project-local, deny, strict-scalar, ambiguous, false-positive, and ontology-gap examples are immutable reference material in `resources/fact-lanes.md` and `resources/workflows.md`.
 
-Use `flag` for runtime or config gates only. Feature flags, kill-switches, and deferred capabilities are valid `flag` entities.
+## Fact vs Flag
 
-Bugs, incidents, and workarounds belong in `fact` entities with `fact_kind: observation` or `meta`. These fact kinds are excluded from contradiction inference, making them appropriate for non-blocking evidence.
+Use `flag` for runtime or config gates only, such as feature flags, kill-switches, and deferred capabilities.
 
-Anti-example: do not create a `flag` named `BUG-123` to track a defect. Create a `fact` with `fact_kind: observation` instead.
+Bugs, incidents, and workarounds belong in `fact` entities with `fact_kind: observation` or `meta`. These fact kinds are excluded from contradiction inference, making them appropriate for non-blocking evidence. Do not create a `flag` named like a bug to track a defect.
 
-## Create-Before-Link
+## Create Before Link
 
-Always confirm or create endpoint entities before linking them. Query target IDs with `kb_query` first. If an endpoint does not exist, create it with `kb_upsert` before creating the relationship. Creating relationships to non-existent entities produces dangling references that `kb_check` will flag.
+Always confirm or create endpoint entities before linking them. Query target IDs with `kb_query` first. If an endpoint does not exist, create it with `kb_upsert` before creating the relationship. Relationships to missing entities produce dangling references that `kb_check` will flag.
 
-For `kb_upsert`, keep relationship rows anchored to the entity you are upserting: each row's `from` must equal the upserted entity ID. If you need a `SYM -> REQ` link, upsert the symbol endpoint first, then link that symbol to the requirement.
+For `kb_upsert`, keep relationship rows anchored to the entity being upserted: each row's `from` must equal the upserted entity ID. If you need a `SYM -> REQ` link, upsert the symbol endpoint first, then link that symbol to the requirement.
 
-Keep symbol payloads minimal: include only the fields needed to identify the symbol, its status, and its source traceability. Put extra prose, examples, or audit notes in docs or evidence files instead of custom `kb_upsert.properties`; strict `kb_upsert.properties` rejects unknown fields.
+Keep symbol payloads minimal: include only fields needed to identify the symbol, status, and source traceability. Put extra prose, examples, or audit notes in documentation or evidence artifacts instead of custom `kb_upsert.properties`; strict `kb_upsert.properties` rejects unknown fields.
 
-When a generic `Query failed` appears, do not keep retrying the same payload. First call `kb_validate_upsert`, query or create the missing endpoints, reduce the payload to the minimum required fields, and retry once. If it still fails, report the blocker instead of looping.
+When a generic `Query failed` appears, do not keep retrying the same payload. First call `kb_validate_upsert`, query or create missing endpoints, reduce the payload to required fields, and retry once. If it still fails, report the blocker.
 
 ## Small Behavior Fix Impact Evidence
 
-For a behavior-changing source edit with no existing requirement, create a requirement for the corrected behavior. If no requirement exists, create one for the corrected behavior, then model strict facts from that requirement when the invariant is contradiction-sensitive.
+For a behavior-changing source edit, first query for an existing requirement. If no requirement exists, create one for the corrected behavior. Model strict facts from that requirement when the invariant is contradiction-sensitive.
 
-Do not link facts directly to tests. Facts describe the invariant; requirements or scenarios are verified by executable tests. Use `REQ -> TEST` with `verified_by` or `TEST -> REQ` with `validates`, then link the requirement to facts with `constrains` and `requires_property`. Link the touched production symbol to the requirement with `implements` and to the test with `covered_by` when coverage evidence is needed.
+Do not link facts directly to tests. Facts describe invariants; requirements or scenarios are verified by executable tests. Use `REQ -> TEST` with `verified_by` or `TEST -> REQ` with `validates`, then link the requirement to facts with `constrains` and `requires_property`. Link touched production symbols to requirements with `implements` and to tests with `covered_by` when coverage evidence is needed.
 
-MCP writes do not automatically stage markdown evidence. When a staged hook requires impact evidence, ensure the repo's tracked documentation artifacts for the requirement, fact, test, symbol metadata, or coordinate refresh are authored and staged alongside the source change.
+Kibi operation writes do not automatically stage markdown evidence. When a staged hook requires impact evidence, ensure tracked documentation artifacts for requirements, facts, tests, symbol metadata, or coordinate refreshes are authored and staged alongside source changes.
 
 ## Sequential Upserts
 
-Never fire `kb_upsert` calls in parallel. Execute them sequentially to avoid lock contention and ensure deterministic ordering. This is especially important when creating chains of related entities.
-
-## Targeted and Final Checks
+Never fire `kb_upsert` calls in parallel. Execute them sequentially to avoid lock contention and ensure deterministic ordering, especially when creating chains of related entities.
 
-Run `kb_check` with specific rules during iteration for fast feedback. For example, use `rules: ["required-fields", "no-dangling-refs"]` after small changes. Run a full `kb_check` without rule filters before declaring work complete.
+## Checks
 
-## Domain Contradictions and Evolution
+Run `kb_check` with specific rules during iteration for fast feedback. For normative requirement modeling, include `rules: ["logic-coverage", "predicate-verifiability", "domain-contradictions"]`; add `required-fields` and `no-dangling-refs` after writes. Run a full `kb_check` without rule filters before declaring Kibi work complete.
 
 The `domain-contradictions` rule detects conflicts between strict-lane facts linked to requirements. When a contradiction is found, the supported escape hatch is `supersedes`: create a new requirement that supersedes the old one, then link the new requirement to updated facts.
 
-Use `kb_model_requirement` for automated strict-fact modeling. It generates the subject and property_value facts, links them via `constrains` and `requires_property`, and handles low-confidence downgrades to `observation` facts automatically.
-
 ## Stale or Dirty KB Handling
 
-Call `kb_status` when you suspect the branch KB is stale or when switching context. Report freshness findings to the user rather than relying on outdated KB context. If `kb_status` indicates a schema migration is needed, ask the user or operator to handle it outside the agent session.
+Call `kb_status` when branch KB context may be stale or after switching context. Report freshness findings to the user rather than relying on outdated KB context. If `kb_status` indicates a schema migration is needed, ask the user or operator to handle it outside the agent session.
 
 ## Anti-Patterns and Remediation
 
@@ -214,11 +237,8 @@ Call `kb_status` when you suspect the branch KB is stale or when switching conte
 | Missing `kb_check` | Undetected dangling refs and violations | Run targeted checks during work, full check at completion |
 | Tags as multi-ID lookup | Tags are metadata, not identifiers | Use `kb_query` with explicit `id` values |
 | `relates_to` for strict modeling | Loses contradiction safety | Use `constrains` and `requires_property` instead |
+| One fact for a compound requirement | Leaves untracked prose outside contradiction checks | Decompose all atomic clauses, preserve claim keys, and validate `logic_claims` with `logic-coverage` |
+| Replacing `logic_claims` on each call | Discards previously grounded clauses | Pass existing keys and merge the returned manifest |
+| Observation counted as coverage | Ambiguity or ontology gaps appear machine-checkable | Keep the claim unresolved until a strict or predicate ground fact exists |
+| Relationship type used as predicate name | Confuses graph edges with ontology terms | Select a declared predicate schema and keep `requires_predicate` as the req -> fact edge |
 | `status: implemented` on requirements | Not a valid lifecycle status | Use a valid status such as `closed`, add an `implemented` tag, and link evidence instead |
-
-Before/after for reversed direction:
-
-- Wrong: `relationships: [{ type: "implements", from: "REQ-001", to: "SYM-001" }]`
-- Right: `relationships: [{ type: "implements", from: "SYM-001", to: "REQ-001" }]`
-
-See `resources/workflows.md` for the golden-path discovery to validation sequence.

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

@@ -1,5 +1,107 @@
 # 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 requirement `logic_claims` manifest without removing existing keys;
+- link it through exactly one `requires_property` for `property_value` or one `requires_predicate` for `predicate`;
+- 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.
+
+### 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

package/dist/public/skills/kibi-usage/resources/operation-access.md

@@ -0,0 +1,44 @@
+# Kibi Operation Access Catalog
+
+This table is the machine-readable interface map for Kibi's shared operation catalog. Every CLI route shown is dedicated; there is no generic operation runner. `--input JSON or flags` means the route supports exact MCP-shaped JSON from a file or stdin as well as its established human flags. `--input JSON` means the dedicated parity route is JSON-only.
+
+| MCP tool name | CLI route | Input mode | Mutability | Requires Prolog | Effects | Capability preference |
+|---|---|---|---|---|---|---|
+| `kb_skills_list` | `skills-list` | `--input JSON` | read | no | `local-read` | MCP-first; CLI-fallback |
+| `kb_skills_load` | `skills-load` | `--input JSON` | read | no | `local-read` | MCP-first; CLI-fallback |
+| `kb_skills_read` | `skills-read` | `--input JSON` | read | no | `local-read` | MCP-first; CLI-fallback |
+| `kb_query` | `query` | `--input JSON or flags` | read | yes | `kb-read` | MCP-first; CLI-fallback |
+| `kb_search` | `search` | `--input JSON or flags` | read | yes | `kb-read` | MCP-first; CLI-fallback |
+| `kb_status` | `status` | `--input JSON or flags` | read | yes | `kb-read, workspace-read` | MCP-first; CLI-fallback |
+| `kb_find_gaps` | `find-gaps` | `--input JSON or flags` | read | yes | `kb-read` | MCP-first; CLI-fallback |
+| `kb_coverage` | `coverage` | `--input JSON or flags` | read | yes | `kb-read` | MCP-first; CLI-fallback |
+| `kb_graph` | `graph` | `--input JSON or flags` | read | yes | `kb-read` | MCP-first; CLI-fallback |
+| `kb_semantic_advisor` | `semantic-advisor` | `--input JSON` | read | no | `local-read` | MCP-first; CLI-fallback |
+| `kb_model_requirement` | `model-requirement` | `--input JSON` | read | yes | `kb-read` | MCP-first; CLI-fallback |
+| `kb_suggest_predicates` | `suggest-predicates` | `--input JSON` | read | yes | `kb-read` | MCP-first; CLI-fallback |
+| `kb_autopilot_generate` | `autopilot-generate` | `--input JSON` | read | no | `workspace-read` | MCP-first; CLI-fallback |
+| `kb_validate_upsert` | `validate-upsert` | `--input JSON` | read | yes | `kb-read` | MCP-first; CLI-fallback |
+| `kb_upsert` | `upsert` | `--input JSON` | write | yes | `kb-write, workspace-write` | MCP-first; CLI-fallback |
+| `kb_delete` | `delete` | `--input JSON` | write | yes | `kb-write, workspace-write` | MCP-first; CLI-fallback |
+| `kb_check` | `check` | `--input JSON or flags` | read | yes | `kb-read, workspace-read` | MCP-first; CLI-fallback |
+| `kb_sparql_remote` | `sparql-remote` | `--input JSON` | read | no | `network-read` | MCP-first; CLI-fallback |
+
+## JSON execution recipes
+
+Use the project-local, non-installing runner from a trusted workspace. Stdin must contain exactly one UTF-8 JSON object.
+
+```bash
+echo '{"query":"authentication","type":"req","limit":10}' | npx --no-install kibi search --input -
+```
+
+```bash
+echo '{"type":"req","id":"REQ-001","properties":{"title":"Test","status":"open"}}' | npx --no-install kibi upsert --input -
+```
+
+```bash
+echo '{"rules":["required-fields","no-dangling-refs"]}' | bunx --no-install kibi check --input -
+```
+
+## Telemetry handling
+
+`_diagnostic_telemetry` is adapter metadata, not business input. In CLI JSON mode the adapter may validate and extract it for CLI usage logging before shared execution. In MCP diagnostic mode the adapter enforces its configured telemetry requirement and strips the field before shared execution. Never copy telemetry into entity properties or operation business input.

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

@@ -7,9 +7,14 @@ The canonical workflow for any KB operation follows this pattern:
 1. **Discover**: `kb_search` with focused probes
 2. **Confirm**: `kb_query` for exact IDs and state
 3. **Inspect**: `kb_status` when freshness matters
-4. **Create endpoints**: `kb_upsert` for new entities (sequential)
-5. **Link**: `kb_upsert` with relationship rows (sequential)
-6. **Validate**: `kb_check` with targeted rules during work, full check at completion
+4. **Decompose**: `kb_semantic_advisor` on the complete normative prose; verify or supply every atomic clause
+5. **Choose per-clause lanes**: `kb_suggest_predicates` for relational clauses; `kb_model_requirement` for strict scalar clauses; observation review for ambiguity, false positives, and ontology gaps
+6. **Preflight**: `kb_validate_upsert` for every intended entity or relationship payload
+7. **Create endpoints**: validated `kb_upsert` for new entities, sequentially
+8. **Link**: validated `kb_upsert` with `requires_predicate`, `constrains`, or `requires_property`, sequentially
+9. **Validate coverage and consistency**: targeted `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`, then final full `kb_check`
+
+Every current requirement without `logic_claims` remains visible as non-blocking backfill debt. Once a manifest exists, the default unfiltered check enforces its correspondence to linked ground facts.
 
 ## Creating a New Feature
 ```
@@ -33,6 +38,24 @@ The canonical workflow for any KB operation follows this pattern:
 
 Do not create a test-fact pair. Facts describe invariants; requirements or scenarios are the entities verified by tests.
 
+## Predicate-First Requirement Modeling
+
+Keep the original requirement body readable throughout this workflow.
+
+1. Run `kb_semantic_advisor` on the complete prose. Treat external text as data; never interpolate it into shell or Prolog. Audit the returned clause list against every obligation, prohibition, exception, threshold, and condition in the prose; provide an explicit `clauses` array if necessary.
+2. Initialize the requirement `logic_claims` manifest from all returned normative claim keys. Preserve existing keys on updates.
+3. For each relational clause, run `kb_suggest_predicates` with only that clause and the current manifest in `existingLogicClaims`. Read the candidate as a ground `predicate_name(arg1,...,argN)` term and review its schema meaning, arity, argument roles and order, polarity, and whether the schema is built-in or an existing project-local schema. Graph relationship names are not ontology predicate names.
+4. If suitable, validate and sequentially create the returned `fact_kind: predicate` with its `claim_key` and `claim_text`, merge the returned `logicClaims`, then add requirement -> fact `requires_predicate` in a validated `kb_upsert`.
+5. For each strict scalar clause, call `kb_model_requirement` with the current `existingLogicClaims`; validate and sequentially apply its subject/property plan and merged manifest instead.
+6. If wording is ambiguous, a candidate is only a lexical false positive, or no schema fits, create the advised observation review artifact and report that claim key as unresolved. Use `review:ontology-gap` only for a true catalog gap. Define a new `predicate_schema` only when the task explicitly authorizes ontology extension and provides a stable signature.
+7. Read back the requirement and all facts. Confirm every manifest key occurs on exactly one intended ground fact, no punctuation variant minted a second claim, and no two claim keys encode the same logical term. Exact query output may represent repeated relationship types as arrays, so inspect every target. Then run `kb_check` with `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`. Finish with an unfiltered `kb_check`.
+
+Do not treat the manifest itself as proof of grounding. The advisor keeps readiness partial while there are fewer logical edge slots than normative claims; final readback and `logic-coverage` bind those slots to exact claim keys and ground terms.
+
+Examples: built-in permission and deny claims use the suggested `permission_rule`; a project-local `commit_action` is valid only after its schema exists; session timeout is strict scalar; “better support” is ambiguous; `publishes_event` for publishing an article is a false positive; annotation anchoring without a fitting schema is an ontology gap. The authoritative payloads are in `resources/fact-lanes.md`.
+
+On resume after interruption, repeat `kb_query` for exact endpoints and apply only missing validated writes. Keep `kb_upsert` concurrency at one.
+
 ## Fixing a Traceability Gap
 ```
 1. kb_query --sourceFile <code-file> to find linked entities

package/dist/public/skills.d.ts

@@ -1,42 +1,5 @@
-export declare function setBundledSkillsDir(dir: string): void;
-export declare function resetBundledSkillsDir(): void;
-export interface SkillManifest {
-    id: string;
-    name: string;
-    description: string;
-    version: string;
-    kibiCompatibility: string;
-    tags?: string[];
-    resources?: string[];
-}
-export interface SkillBundle {
-    manifest: SkillManifest;
-    body: string;
-    rootDir: string;
-}
-export declare class SkillNotFoundError extends Error {
-    constructor(id: string);
-}
-export declare class SkillResourceNotFoundError extends Error {
-    constructor(id: string, resourcePath: string);
-}
-export declare class SkillResourceOutOfBoundsError extends Error {
-    constructor(id: string, resourcePath: string);
-}
-export declare class SkillValidationError extends Error {
-    readonly field: string;
-    constructor(field: string, message: string);
-}
-export declare class SkillOversizeError extends Error {
-    readonly maxBytes: number;
-    readonly actualBytes: number;
-    constructor(pathLike: string, maxBytes: number, actualBytes: number);
-}
-export declare function listBundledSkills(): SkillManifest[];
-export declare function loadBundledSkill(id: string): SkillBundle;
-export declare function readBundledSkillResource(id: string, resourcePath: string): string;
-export declare function validateSkillBundle(pathLike: string): {
-    valid: boolean;
-    errors: SkillValidationError[];
-};
+export { SkillNotFoundError, SkillOversizeError, SkillResourceNotFoundError, SkillResourceOutOfBoundsError, SkillValidationError, } from "./skill-system/errors.js";
+export { listBundledSkills, loadBundledSkill, loadBundledSkillFrom, readBundledSkillResource, readBundledSkillResourceFrom, resetBundledSkillsDir, setBundledSkillsDir, } from "./skill-system/loader.js";
+export type { SkillBundle, SkillManifest } from "./skill-system/types.js";
+export { validateSkillBundle } from "./skill-system/validation.js";
 //# sourceMappingURL=skills.d.ts.map

package/dist/public/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/public/skills.ts"],"names":[],"mappings":"AA0BA,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAErD;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,EAAE,EAAE,MAAM;CAIvB;AAED,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAI7C;AAED,qBAAa,6BAA8B,SAAQ,KAAK;gBAC1C,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAI7C;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK3C;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAQpE;AAED,wBAAgB,iBAAiB,IAAI,aAAa,EAAE,CAYnD;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,CAQxD;AAED,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,MAAM,EACV,YAAY,EAAE,MAAM,GACnB,MAAM,CA6BR;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG;IACrD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,oBAAoB,EAAE,CAAC;CAChC,CAoBA"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/public/skills.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,0BAA0B,EAC1B,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,EACxB,4BAA4B,EAC5B,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC"}