kibi-cursor 0.5.0 → 0.5.1

package/agent-plugin/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 requirement `logic_claims` manifest without removing existing keys;
+- 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/agent-plugin/skills/kibi-usage/resources/logic-ir.md

@@ -0,0 +1,43 @@
+# Typed Logic IR and Proposition Coverage
+
+Kibi stores human prose as readable requirement text, but verifiable meaning belongs in typed facts and `kibi.logic.v1` rule facts. The host agent may propose an interpretation; Kibi validates, canonicalizes, hashes, persists, and reasons over it. Never submit a Prolog source string, goal, module, or function symbol. Rendered Prolog is an inspection preview only.
+
+## Two-pass extraction
+
+1. Run `kb_semantic_advisor` over the complete text. Supply explicit `clauses` when sentence splitting could hide a condition, exception, definition, descriptive assertion, threshold, quantity, or temporal qualifier.
+2. Audit the returned `propositions` against the original UTF-8 text. Every assertive span must be `modeled`, `ambiguous`, `ontology_gap`, or `missing`; rationale, examples, and subjective commentary are `nonlogical` and remain readable prose.
+3. For each assertive proposition, submit up to three typed `interpretations` when alternatives are plausible. Kibi compares canonical semantic keys; materially different valid interpretations remain unresolved regardless of confidence.
+4. Apply only a validated plan, then read back the requirement, rule schema, rule fact, and all relationship targets. Run `rule-safety`, `rule-verifiability`, `semantic-completeness`, `logic-coverage`, and `domain-contradictions` before the final unfiltered check.
+
+When a project-local schema names several ordered arguments, those arguments are facets of one relation, not separate propositions. Preserve the advisor claim key for the complete relation and do not manufacture clauses for each argument. Supporting `predicate_schema` facts carry the declared signature only; the ground predicate fact carries the claim provenance. Apply the exact `kb_suggest_predicates`/`kb_model_requirement` plan, reducing a rejected schema payload through `kb_validate_upsert` rather than silently downgrading a fitting declared relation to an observation.
+
+## Logic IR shape
+
+The supported v1 forms are:
+
+- `kind: atom` with a ground `head`;
+- `kind: rule` with a range-restricted `head` and `body`;
+- `kind: constraint` with a body and no head.
+
+Terms are typed `const`, `var`, `number`, `duration`, or ISO `timestamp`. Variables are explicitly declared as `forall` (the default) or body-local `exists`; an existential variable may not occur in a rule head. Bodies use `all`, `any`, closed-world `not`, comparisons, bounded `count`, and bounded temporal expressions. Modalities are `assert`, `deny`, `oblige`, `permit`, and `forbid`.
+
+Every head and body variable must be bound by a positive atom. Negation is allowed only on an atom with `closedWorld: true`, and only when its variables are also positively bound. Function symbols, raw goals, cuts, meta-calls, dynamic predicates, I/O, unbounded aggregation, unsafe variables, and unstratified negation are rejected before persistence.
+
+Example (inspection data, not executable input):
+
+```json
+{
+  "version": "kibi.logic.v1",
+  "kind": "rule",
+  "modality": "oblige",
+  "variables": [{"name": "U", "type": "user", "quantifier": "forall"}],
+  "head": {"kind": "atom", "name": "audit", "args": [{"kind": "var", "name": "U", "type": "user"}]},
+  "body": {"kind": "atom", "name": "admin_action", "args": [{"kind": "var", "name": "U", "type": "user"}]}
+}
+```
+
+Use `rule_schema` facts for stable predicate signatures and link a requirement to a `rule` fact with `requires_rule`. Keep `logic_claims` for backward-compatible ground claim manifests; `semantic_inventory` is the complete proposition ledger. A manifest is not proof until each key is linked to exactly one intended fact and the rule checks pass.
+
+## Contradictions and uncertainty
+
+Kibi compares opposing modalities over matching heads and overlapping authority, scope, and validity intervals. `assert`/`deny`, `oblige`/`forbid`, and overlapping `permit`/`forbid` pairs can be contradictory. Different conditions, unresolved interpretations, unsupported ontology terms, analysis limits, and incomplete closure produce `unresolved`, never a false consistency proof. Preserve superseding requirements rather than deleting historical claims.

package/agent-plugin/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 | Interface |
+|---|---|---|---|---|---|---|
+| `kb_skills_list` | `skills-list` | `--input JSON` | read | no | `local-read` | peer; capability-selected |
+| `kb_skills_load` | `skills-load` | `--input JSON` | read | no | `local-read` | peer; capability-selected |
+| `kb_skills_read` | `skills-read` | `--input JSON` | read | no | `local-read` | peer; capability-selected |
+| `kb_query` | `query` | `--input JSON or flags` | read | yes | `kb-read` | peer; capability-selected |
+| `kb_search` | `search` | `--input JSON or flags` | read | yes | `kb-read` | peer; capability-selected |
+| `kb_status` | `status` | `--input JSON or flags` | read | yes | `kb-read, workspace-read` | peer; capability-selected |
+| `kb_find_gaps` | `find-gaps` | `--input JSON or flags` | read | yes | `kb-read` | peer; capability-selected |
+| `kb_coverage` | `coverage` | `--input JSON or flags` | read | yes | `kb-read` | peer; capability-selected |
+| `kb_graph` | `graph` | `--input JSON or flags` | read | yes | `kb-read` | peer; capability-selected |
+| `kb_semantic_advisor` | `semantic-advisor` | `--input JSON` | read | no | `local-read` | peer; capability-selected |
+| `kb_model_requirement` | `model-requirement` | `--input JSON` | read | yes | `kb-read` | peer; capability-selected |
+| `kb_suggest_predicates` | `suggest-predicates` | `--input JSON` | read | yes | `kb-read` | peer; capability-selected |
+| `kb_autopilot_generate` | `autopilot-generate` | `--input JSON` | read | no | `workspace-read` | peer; capability-selected |
+| `kb_validate_upsert` | `validate-upsert` | `--input JSON` | read | yes | `kb-read` | peer; capability-selected |
+| `kb_upsert` | `upsert` | `--input JSON` | write | yes | `kb-write, workspace-write` | peer; capability-selected |
+| `kb_delete` | `delete` | `--input JSON` | write | yes | `kb-write, workspace-write` | peer; capability-selected |
+| `kb_check` | `check` | `--input JSON or flags` | read | yes | `kb-read, workspace-read` | peer; capability-selected |
+| `kb_sparql_remote` | `sparql-remote` | `--input JSON` | read | no | `network-read` | peer; capability-selected |
+
+## 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/agent-plugin/skills/kibi-usage/resources/relationship-directions.md

@@ -0,0 +1,119 @@
+# Relationship Directions
+
+## Direction Table
+
+| Relationship | Source -> Target | Semantic Meaning |
+|-------------|------------------|------------------|
+| `implements` | symbol -> req | Production code symbol owns or implements requirement behavior |
+| `specified_by` | req -> scenario | Requirement is specified by a BDD scenario |
+| `verified_by` | req/scenario -> test | Requirement or scenario is verified by a test case |
+| `validates` | test -> req/scenario | Test validates a requirement or scenario (inverse of verified_by) |
+| `executable_for` | symbol -> test | Test symbol (code) is executable code for a test entity |
+| `constrains` | req -> fact(subject) | Requirement constrains a strict-lane domain fact |
+| `requires_property` | req -> fact(property_value) | Requirement requires a specific property value fact |
+| `supersedes` | old-req -> new-req | Old requirement is formally replaced by a new requirement |
+| `covered_by` | symbol -> test | Production symbol has test coverage evidence |
+
+## Valid Payload Examples
+
+### implements
+```yaml
+relationships:
+  - type: implements
+    from: SYM-001
+    to: REQ-001
+```
+
+### specified_by
+```yaml
+relationships:
+  - type: specified_by
+    from: REQ-001
+    to: SCEN-001
+```
+
+### verified_by
+```yaml
+relationships:
+  - type: verified_by
+    from: REQ-001
+    to: TEST-001
+```
+
+### validates
+```yaml
+relationships:
+  - type: validates
+    from: TEST-001
+    to: SCEN-001
+```
+
+### executable_for
+```yaml
+relationships:
+  - type: executable_for
+    from: SYM-test-login
+    to: TEST-001
+```
+
+### constrains
+```yaml
+relationships:
+  - type: constrains
+    from: REQ-019
+    to: FACT-USER-ROLE
+```
+
+### requires_property
+```yaml
+relationships:
+  - type: requires_property
+    from: REQ-019
+    to: FACT-LIMIT-3
+```
+
+### supersedes
+```yaml
+relationships:
+  - type: supersedes
+    from: REQ-001
+    to: REQ-001-v2
+```
+
+### covered_by
+```yaml
+relationships:
+  - type: covered_by
+    from: SYM-handler
+    to: TEST-005
+```
+
+## Invalid Test-Fact Shortcuts
+
+Do not model small behavior fixes as direct test-fact pairs. Facts describe invariants; requirements or scenarios are verified by tests.
+
+```yaml
+# WRONG: fact -> test is not a valid verified_by shape
+relationships:
+  - type: verified_by
+    from: FACT-HEADER-AVATAR-INITIAL-UPPERCASE
+    to: TEST-AVATAR-HEADER-FALLBACK
+
+# WRONG: test -> fact is not a valid validates shape
+relationships:
+  - type: validates
+    from: TEST-AVATAR-HEADER-FALLBACK
+    to: FACT-HEADER-AVATAR-INITIAL-UPPERCASE
+```
+
+Use a requirement as the verification target/source, then link that requirement to strict facts:
+
+```yaml
+relationships:
+  - type: verified_by
+    from: REQ-HEADER-AVATAR-INITIAL-UPPERCASE
+    to: TEST-AVATAR-HEADER-FALLBACK
+  - type: requires_property
+    from: REQ-HEADER-AVATAR-INITIAL-UPPERCASE
+    to: FACT-HEADER-AVATAR-INITIAL-UPPERCASE
+```

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

@@ -0,0 +1,96 @@
+# UI / Visual Requirement Modeling
+
+Optional, per-project lane for recording what the screen should look like so UI edits cannot
+silently drift from the spec. Non-UI projects skip it entirely; no check rule requires it.
+
+## Three layers
+
+1. **Prose `req`** — the full on-screen description lives in the requirement body as the
+   searchable anchor agents discover with `kb_search` / `kb_query`.
+2. **Strict facts** — checkable visual invariants as `fact_kind: subject` (`subject_key`,
+   linked `constrains`) plus `fact_kind: property_value` (`property_key`, `operator`, typed
+   `value_*`, linked `requires_property`). Incompatible values on the same subject/property
+   from two current requirements are rejected on write unless `supersedes`.
+3. **Relational predicates** — ground `fact_kind: predicate` linked with `requires_predicate`.
+   The built-in `visual_layout_rule(subject, relation, target)` covers "X must remain visually
+   aligned with Y" (relation `aligned_with`). Other relational layout claims need a
+   project-local `predicate_schema` when the task authorizes ontology extension.
+
+Kibi enforces stated facts and links, not pixels. Freeform spatial prose is stored and
+searchable but is not machine-checked.
+
+## Button position
+
+```yaml
+id: FACT-UI-SUBMIT-REGION
+fact_kind: subject
+subject_key: settings.screen.submit_button
+```
+
+```yaml
+id: FACT-UI-SUBMIT-POSITION
+fact_kind: property_value
+subject_key: settings.screen.submit_button
+property_key: position
+operator: eq
+value_type: string
+value_string: bottom_right
+canonical_key: settings.screen.submit_button.position.eq.bottom_right
+```
+
+Link both facts from the requirement:
+
+```yaml
+id: REQ-UI-SETTINGS
+relationships:
+  - type: constrains
+    from: REQ-UI-SETTINGS
+    to: FACT-UI-SUBMIT-REGION
+  - type: requires_property
+    from: REQ-UI-SETTINGS
+    to: FACT-UI-SUBMIT-POSITION
+```
+
+A later requirement writing `position: top_left` on the same subject is rejected on write.
+
+## Header item order
+
+Use one indexed `property_key` per slot against the same subject region:
+`nav_order_1: home`, `nav_order_2: search`, `nav_order_3: profile`, each as a separate
+`property_value` fact linked with `requires_property`. This makes each slot independently
+contradiction-checkable.
+
+## Relational alignment
+
+```yaml
+id: FACT-UI-NAV-ALIGN
+fact_kind: predicate
+predicate_name: visual_layout_rule
+predicate_args: [navigation_rail, aligned_with, header]
+polarity: assert
+canonical_key: visual_layout_rule(navigation_rail,aligned_with,header)
+```
+
+Link with `requires_predicate`. An `assert`/`deny` pair over the same predicate namespace,
+name, and ordered arguments is a blocking `domain-contradictions` conflict.
+
+## UI component traceability
+
+Model the component as a `symbol` with `sourceFile` and `symbol_role: behavioral`, linked
+`implements` to the requirement, so component edits surface the visual spec in impact
+diagnostics (`symbol_semantic_review_needed`).
+
+## Workflow
+
+1. `kb_semantic_advisor` on the full description; audit or supply `clauses`.
+2. Relational clauses: `kb_suggest_predicates`, apply the predicate plan and
+   `requires_predicate`.
+3. Scalar placement/alignment/order clauses: `kb_model_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.
+5. `kb_validate_upsert`, create endpoints first, then sequential `kb_upsert`.
+6. `kb_check` with `logic-coverage`, `predicate-verifiability`, `domain-contradictions`,
+   then a final unfiltered `kb_check`.
+
+Non-UI projects: declare `has_ui: false` during bootstrap and no UI entities are proposed.

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

@@ -0,0 +1,80 @@
+# Workflows
+
+## Discovery to Validation Sequence
+
+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. **Decompose**: `kb_semantic_advisor` on the complete normative prose; verify or supply every atomic clause
+5. **Choose per-clause lanes**: strict facts for scalar claims; `kb_suggest_predicates` for approved ground ontology relations; `kb_model_requirement` with `kibi.logic.v1` for conditions, exceptions, modalities, quantifiers, cardinality, and bounded temporal rules; observation review for ambiguity, nonlogical prose, 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_rule`, `requires_predicate`, `constrains`, or `requires_property`, sequentially
+9. **Validate coverage and consistency**: targeted `rule-safety`, `rule-verifiability`, `semantic-completeness`, `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 and `semantic_inventory` exist, the unfiltered check enforces correspondence to linked ground facts/rules and rejects silently missing assertive propositions.
+
+## Creating a New Feature
+```
+1. kb_search to discover existing requirements and related knowledge
+2. kb_query to confirm exact IDs and source-linked context
+3. kb_upsert for new or updated requirements (include relationship rows)
+4. kb_check with targeted rules
+```
+
+## Small Behavior Fix With No Existing Requirement
+```
+1. kb_search and kb_query by the changed source file and test file.
+2. If no requirement exists, create a REQ for the corrected behavior.
+3. Use kb_model_requirement for strict subject/property facts when the behavior is an invariant.
+4. Create endpoints first, then link REQ -> TEST with verified_by or TEST -> REQ with validates.
+5. Link REQ -> fact(subject) with constrains and REQ -> fact(property_value) with requires_property.
+6. Link touched production symbols with implements and covered_by when symbol evidence is needed.
+7. Author and stage tracked markdown/symbol evidence; MCP writes do not stage those files automatically.
+8. Run kb_check with targeted rules, then a final full check.
+```
+
+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. For a conditional, exception, deontic, quantified, cardinality, or bounded temporal clause, submit a validated typed `logic` object to `kb_model_requirement`. Apply its `rule_schema` and `rule` facts sequentially and link the requirement with `requires_rule`; rendered Prolog is for inspection only.
+7. If wording is ambiguous, a candidate is only a lexical false positive, or no schema/IR interpretation fits, create the advised observation review artifact and apply its returned `relates_to` review anchor when present; report that claim key as unresolved. Use `review:ambiguity` for unresolved interpretation, `review:keyword-false-positive` for a vocabulary match that is not a domain assertion, and `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.
+8. Read back the requirement, proposition ledger, and all facts. Confirm every manifest key occurs on exactly one intended ground fact/rule, 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 `rule-safety`, `rule-verifiability`, `semantic-completeness`, `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.
+
+## UI / Visual Requirement Modeling
+
+Optional per-project workflow for recording what the screen should look like. Non-UI projects skip this lane entirely.
+
+1. Create a prose `req` holding the full visual description; it is the searchable anchor agents discover before touching a UI file.
+2. Run `kb_semantic_advisor` on the description; audit or supply `clauses`.
+3. For relational layout clauses ("X must remain visually aligned with Y"), call `kb_suggest_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_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.
+6. Model UI components as `symbol` entities with `sourceFile` and `symbol_role: behavioral`, linked `implements` to the requirement.
+7. `kb_validate_upsert`, create endpoints first, then sequential `kb_upsert`. Run `kb_check` with `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`, then a final unfiltered `kb_check`.
+
+Incompatible values on the same subject/property from two current requirements are rejected on write; change an intentional value via a replacement requirement linked with `supersedes`. Full payloads are in `resources/ui-requirements.md`.
+
+## Fixing a Traceability Gap
+```
+1. kb_query --sourceFile <code-file> to find linked entities
+2. kb_find_gaps --type req --missing-rel specified_by to find orphan requirements
+3. kb_upsert to add missing relationship rows (sequential)
+4. kb_check with rules: ["no-dangling-refs", "symbol-traceability"]
+```

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

@@ -1,7 +1,7 @@
 {
   "name": "kibi-cursor",
   "displayName": "Kibi",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Optional Cursor adapter for Kibi. Requires SWI-Prolog 9+ and project-local kibi-cli, kibi-mcp, and kibi-core before the bundled MCP server can start.",
   "license": "AGPL-3.0-or-later",
   "author": {

package/dist/messages.d.ts

@@ -1,7 +1,7 @@
 import type { HookState } from "./hook-state.js";
 import { type McpState } from "./kb-mcp-tools.js";
-export declare const BOOTSTRAP_REMINDER = "Kibi config was not found at the Cursor workspace root. Use visible Kibi MCP tools, or a trusted project-local CLI JSON route with --input when MCP is unavailable, to bootstrap project memory; if neither interface is available, tell the operator. Do not read or edit `.kb/` files directly. Query before mutate, run kb_upsert sequentially, and run kb_check before completion.";
-export declare const DIRECT_KB_EDIT_WARNING = "Do not read or edit `.kb/` files directly. Use visible Kibi MCP tools, or trusted project-local CLI JSON routes with --input when MCP is unavailable. Query before mutate, run kb_upsert sequentially, and run kb_check before completion.";
+export declare const BOOTSTRAP_REMINDER = "Kibi config was not found at the Cursor workspace root. Use visible Kibi MCP tools or a trusted project-local CLI JSON route with --input (peer surfaces) to bootstrap project memory; if neither interface is available, tell the operator. Do not read or edit `.kb/` files directly. Query before mutate, run kb_upsert sequentially, and run kb_check before completion.";
+export declare const DIRECT_KB_EDIT_WARNING = "Do not read or edit `.kb/` files directly. Use visible Kibi MCP tools or trusted project-local CLI JSON routes with --input (peer surfaces). Query before mutate, run kb_upsert sequentially, and run kb_check before completion.";
 export declare function interfaceAdvisory(mcpState: McpState, workspaceTrusted: boolean): string | undefined;
 export declare function stopFollowupMessage(state: HookState): string | undefined;
 /** @deprecated Use stopFollowupMessage */

package/dist/messages.js

@@ -1,7 +1,7 @@
 import { resolveKibiInterface } from "./kb-mcp-tools.js";
 import { isKbFreshnessRelevantPath, isSourceImpactRelevantPath, } from "./path-policy.js";
-export const BOOTSTRAP_REMINDER = "Kibi config was not found at the Cursor workspace root. Use visible Kibi MCP tools, or a trusted project-local CLI JSON route with --input when MCP is unavailable, to bootstrap project memory; if neither interface is available, tell the operator. Do not read or edit `.kb/` files directly. Query before mutate, run kb_upsert sequentially, and run kb_check before completion.";
-export const DIRECT_KB_EDIT_WARNING = "Do not read or edit `.kb/` files directly. Use visible Kibi MCP tools, or trusted project-local CLI JSON routes with --input when MCP is unavailable. Query before mutate, run kb_upsert sequentially, and run kb_check before completion.";
+export const BOOTSTRAP_REMINDER = "Kibi config was not found at the Cursor workspace root. Use visible Kibi MCP tools or a trusted project-local CLI JSON route with --input (peer surfaces) to bootstrap project memory; if neither interface is available, tell the operator. Do not read or edit `.kb/` files directly. Query before mutate, run kb_upsert sequentially, and run kb_check before completion.";
+export const DIRECT_KB_EDIT_WARNING = "Do not read or edit `.kb/` files directly. Use visible Kibi MCP tools or trusted project-local CLI JSON routes with --input (peer surfaces). Query before mutate, run kb_upsert sequentially, and run kb_check before completion.";
 export function interfaceAdvisory(mcpState, workspaceTrusted) {
     const selectedInterface = resolveKibiInterface(mcpState, workspaceTrusted);
     switch (selectedInterface) {