kibi-cli 0.19.0 → 2.0.0

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

@@ -1,276 +1,181 @@
 ---
 id: kibi-usage
 name: Kibi Usage
-description: Guides agents to use Kibi MCP, facts, relationships, and validation correctly
-version: 1.3.0
-kibiCompatibility: ">=0.11.0"
+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.2
+kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
   - mcp
-  - knowledge-base
+  - cli
+  - source-first
+  - branching
   - traceability
-  - agent-guidance
+  - 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/operation-access.md
+  - resources/proof.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 KB status is suspected, and before mutations.
+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.
 
-## Interface Selection
+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.
 
-Kibi exposes two peer surfaces over the same 18 operations: visible MCP tools and the trusted project-local CLI. Both accept the same business input and effects (see `resources/operation-access.md`). Choose by what is visible and approved in the current environment — MCP and the CLI are equal choices, not a preference order:
+## Interface Selection
 
-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 ...`. The CLI is a peer interface, not a fallback.
-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 whichever capability is visible and approved. The surfaces are equal peers:
 
-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.
+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.
 
-CLI JSON mode accepts MCP-shaped business input at `--input <file|->`.
+Hosts may expose prefixed identifiers such as `kibi_kb_search`,
+`kibi_kb_query`, and `kibi_kb_upsert`; map them to the canonical MCP names.
 
-```bash
-echo '{"type":"req","id":"REQ-001","properties":{"title":"Test","status":"open"}}' | npx --no-install kibi upsert --input -
-```
+The CLI JSON route accepts the same business object as MCP:
 
 ```bash
-echo '{"query":"authentication","limit":10}' | npx --no-install kibi search --input -
-```
-
-## MCP Tool Names
-
-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.
-
-## Discovery First
-
-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.
-
-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.
-
-## Approval Boundaries
-
-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. Reversed links break traceability queries and validation.
-
-| Relationship | Direction | Meaning |
-|-------------|-----------|---------|
-| `implements` | symbol -> req | Symbol owns or implements requirement behavior |
-| `specified_by` | req -> scenario | Requirement is specified by a scenario |
-| `verified_by` | req/scenario -> test | Requirement or scenario is verified by a test |
-| `validates` | test -> req/scenario | Test validates a requirement or scenario |
-| `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 |
-
-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
-
-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.
-
-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
-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
-    to: REQ-ADMIN-BILLING-POLICY
+printf '%s\n' '{"query":"checkout","limit":10}' | npx --no-install kibi search --input -
 ```
 
-## Typed Logic IR Lane
-
-Readable prose is retained for people, while every assertive proposition is inventoried and either grounded in a strict fact, a predicate fact, or a safe typed rule. Use the required extraction pass followed by an adversarial coverage audit; do not let a high-confidence single suggestion stand in for the rest of a compound requirement. Load `resources/logic-ir.md` for the IR grammar, proposition ledger, safety boundary, and proof semantics.
+Read `resources/operation-access.md` for the route, result version, effects,
+mutability, and Prolog requirements of each operation.
 
-Use `kb_semantic_advisor` with up to three typed `interpretations` for ambiguous clauses. Kibi canonicalizes alternatives and keeps materially different meanings unresolved. Create `fact_kind: rule_schema` and `fact_kind: rule` endpoints from `kb_model_requirement`'s validated plan, then link `req -> rule` with `requires_rule`. Run `rule-safety`, `rule-verifiability`, `semantic-completeness`, `logic-coverage`, and `domain-contradictions`; unresolved, incomplete, or timed-out reasoning is not evidence of consistency.
+## Safe workflow
 
-The portable skill body must carry the core contract even when its detailed resources are unavailable: `kb_semantic_advisor` returns a `propositions[]` ledger and `semantic_inventory`; submit typed `interpretations` when wording has more than one plausible logical reading; validate modeled conditions through `kibi.logic.v1`; and preserve unresolved propositions as explicit gaps. Do not read or edit files inside `.kb` directly.
+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
+   report the five independent closeout fields (not one inferred success flag).
 
-Requirement proof also requires fresh execution evidence. Read the available `verificationSnapshot` from `kb_status`, run the scenario-backed E2E command, and append a `kibi.verification-receipt.v1` carrying test ID, typed scope, runner, command, snapshot, environment hash, timestamps, outcome, and artifact digest. Never rewrite receipt history or treat durable `status: passing` as execution proof; re-run coverage and repair every receipt-specific gap.
+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`.
 
-Requirement-mode `kb_coverage` also returns `kibi.repair-plan.v1`. Use it only when `scope.complete` is true; a partial plan means pagination hid actionable requirements. Apply only the earliest `ready` batch for each requirement, query before mutation, create endpoints before relationships, validate every payload, and keep `kb_upsert` calls sequential. Batches are deliberately `autoApplicable: false`: semantic resolution, contradiction supersession, E2E execution, and source ownership always require review. Re-run coverage after every batch instead of continuing from a stale plan.
+For a task that explicitly supplies a malformed concrete mutation payload, locate and read that public request artifact before choosing an entity, preserving its exact entity ID, type, requested changes, and every intended relationship and endpoint. Do not substitute a seeded or convenient entity for the requested target. Start with kb_search, then exact-filter those targets with kb_query, and run kb_validate_upsert on that same payload; validation is not completion. Correct only diagnosed pre-commit errors and revalidate the corrected payload. Once authorized, apply the identical corrected and authorized payload with kb_upsert. If it returns committed_with_repairs, treat the mutation as committed, follow only the required repair actions, and neither retry it nor trigger unrelated semantic backfill for a schema-only repair. Exact-read every changed entity and relationship endpoint with kb_query, then finish with an unfiltered kb_check followed by a final kb_status.
 
-When `.kb/usage.log` exists, treat `kibi.telemetry-acceptance.v1` as the process-evidence lane. Run `kibi usage-metrics --format json --require-acceptance` before completion and inspect unfiltered `kb_check.qualityDiagnostics[]` for ranked `category: telemetry` repairs. The rolling report requires fresh evidence for advisor-before-requirement-write, exact validation-before-upsert, source-linked lookup results, proof-gap recovery, receipt freshness, and mutation retry discipline. `insufficient_evidence` is not a pass: capture current complete coverage and diagnostic events rather than waiving stale, partial, or pre-upgrade logs. A missing usage log means diagnostic logging is not active; do not invent telemetry evidence.
+## Closeout fields
 
-## Strict Fact Lane
+End every task with these five independent fields:
 
-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
-id: FACT-USER-ROLE
-fact_kind: subject
-subject_key: user.role_assignment
+```text
+taskOutcome: complete | interim | blocked
+kbState: clean_fresh | stale | dirty | legacy_compat | not_evaluated
+verificationState: fresh | dirty | unavailable | not_evaluated
+proofState: proven | mixed | unresolved | not_evaluated
+limitationDisposition: none | accepted | unaccepted | not_applicable
 ```
 
-```yaml
-id: REQ-019
-relationships:
-  - type: constrains
-    from: REQ-019
-    to: FACT-USER-ROLE
-  - type: requires_property
-    from: REQ-019
-    to: FACT-LIMIT-3
-```
-
-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 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.
-
-## 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; no check rule requires it.
-
-Use three layers: a prose `req` as the searchable anchor, strict `property_value` facts for checkable positions/alignment/order (linked `constrains` / `requires_property`, so incompatible values on the same subject/property are rejected on write unless `supersedes`), and relational predicates linked with `requires_predicate` (built-in `visual_layout_rule(subject, relation, target)` for "X must remain visually aligned with Y"). Model UI components as `symbol` entities with `sourceFile` and `symbol_role: behavioral`, linked `implements` to the requirement, so component edits surface the visual spec in impact diagnostics. Full payloads and workflow: `resources/ui-requirements.md`.
-
-## Complete Logical Coverage
-
-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 exactly the current assertive proposition keys in the requirement's `logic_claims` manifest. Preserve unrelated metadata, but remove stale claim keys when the source meaning changes; never silently omit an earlier proposition that remains in the current prose.
-4. Ground each key through exactly one suitable logical lane: `requires_property` to one strict `property_value` fact, `requires_predicate` to one ground `predicate` fact, or `requires_rule` to one safe `rule` 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`, `rule-safety`, `rule-verifiability`, `semantic-completeness`, `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. Preserve the advisor's `inventory_contract` as `semantic_inventory_version`, `semantic_source_field`, and `semantic_source_hash`; every ledger span must select its exact claim text from that field. For new or migrated requirements, use requirement-only `semantic_text` for normalized authored prose and keep `text_ref` available for independent code or document evidence. Legacy direct payloads may still declare `text_ref` or `title`; an explicitly declared but empty semantic source fails closed instead of falling through. Mutation rejects duplicate or omitted propositions and requires every `modeled` entry to resolve through exactly one logical edge to a fact with the same claim key. Explicit unresolved entries remain ingestible but cannot prove the requirement.
-
-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
-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.
-```
-
-The example keys are illustrative; use only keys returned for the exact clause text.
+`taskOutcome` is whether the requested work finished. The other fields are
+observed system state. A clean check can coexist with unresolved proof.
+
+## 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`, and `resources/proof.md` for the proof workflow.
 
 ## 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. If lexical rank order prefers a false positive, retry with the reviewed candidate's exact `schema.id` as `schemaId`; do not mutate the candidate or treat a missing schema reference as an ontology gap. If it returns `binding_status: incomplete`, retry with exact `argumentBindings` for every `unbound_arguments` name; its empty `applyPlan` is a safety gate, and the literal `unknown` must never be persisted. Use `polarityHint` only when review of the complete claim proves that surface negation does not deny the selected predicate. Once complete, 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, apply its returned `relates_to` review anchor when present, and report the requirement as logically incomplete. Use `review:ambiguity` for unresolved scope or interpretation and `review:keyword-false-positive` when a vocabulary match is not a domain assertion.
-7. Validate every payload, create endpoints first, apply `kb_upsert` calls sequentially, read back all affected IDs, and run targeted `rule-safety`, `rule-verifiability`, `semantic-completeness`, `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.
-
-### Schema-aware proposition boundary
-
-A declared project-local predicate schema can encode one complete relation whose ordered arguments name several facets of the same claim. Do not split those arguments into separate propositions, invent one predicate per noun, or pass an explicit `clauses` array merely to enumerate the schema arguments. First ask `kb_semantic_advisor` about the complete sentence; add clauses only for independently asserted propositions that are not represented by the selected relation. For a schema-backed relation, preserve the one claim key for the complete relation, create the supporting `predicate_schema` with its minimal declared signature (supporting schemas do not carry `claim_key` or `logic_claims`), call `kb_suggest_predicates` on the complete claim, and apply its exact plan to create one ground predicate fact with the ordered schema arguments and that claim key. If `kb_model_requirement` returns an apply plan, execute that plan sequentially; do not fall back to observation facts when an explicitly declared schema fits. If a schema write is rejected, use `kb_validate_upsert` to reduce it to the supported signature, then retry once before considering an ontology gap.
-
-### Hard lane gates for unresolved prose and supplied schemas
-
-The advisor's proposition `status` is a safety gate, not a confidence hint. A `nonlogical` proposition (including `subjective`, rationale, example, heading, or commentary) never receives a `logic_claims` entry and never goes through `kb_suggest_predicates` or `kb_model_requirement`; preserve the complete prose as one `fact_kind: observation` only when an auditable record is useful. Do not manufacture atomic clauses from a subjective sentence merely because it contains `when`, a domain noun, or the word `predicate`. An `ambiguous` proposition remains an ambiguity observation until the operator supplies a typed interpretation. An `ontology_gap` remains unresolved unless an approved schema or validated IR is actually available.
-
-When authorized task input contains `projectLocalSchemas`, those declarations are the schema authority even if the first advisor or predicate lookup calls them an ontology gap. Do not treat an empty candidate list as final: create the minimal declared `predicate_schema` endpoint first, then call `kb_suggest_predicates` again on the one complete claim (with the current `existingLogicClaims`) and apply the resulting ground predicate plan. Preserve the single claim key for that relation; do not add keys for schema arguments. If the lookup still cannot return a plan after the declared schema exists, validate the exact schema-backed predicate payload once and report the remaining blocker rather than inventing a different predicate. For prohibition cues (`must not`, `never`, `cannot`, `forbidden`), use the positive schema with `polarity: deny`; never silently change it to `assert` or encode the negation in a new predicate name.
-
-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
-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.
-```
-
-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.
-
-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`.
+Call `kb_semantic_advisor` on the complete prose before encoding a clause.
+Set requirement `logic_claims` to exactly the assertive `claim_key` values.
+For each relational clause, call `kb_suggest_predicates` with that clause and
+`existingLogicClaims`. If lexical rank is a false positive, retry with the
+reviewed `schemaId`. If `binding_status` is `incomplete`, supply
+`argumentBindings` and retry. Persist `fact_kind: predicate` with the same
+`claim_key` / `claim_text`, then link `REQ -> fact` with `requires_predicate`.
+Use `kb_model_requirement` for strict scalar clauses. Use
+`fact_kind: observation` only for a true ontology gap. The manifest is not
+grounding: run `logic-coverage` so each key binds to one ground fact.
+Relationship direction is fixed, and every `from` in a relationship batch
+must equal the upserted entity ID.
+
+For conditional relational claims, after the initial `kb_suggest_predicates` and before any `kb_upsert`—including one needed for a missing schema—call read-only `kb_model_requirement` to preview suitable scalar or typed-rule modeling. Treat the preview as advisory: do not apply an irrelevant result or create unrequested facts, and retain an approved ground-predicate plan when it captures the whole claim. Preserve supplied arity, ordered argument roles, polarity, bound values, and one claim key per actual assertion; never split arguments across clauses or schemas or alter values to force uniqueness.
 
-## Fact vs Flag
-
-Use `flag` for runtime or config gates only, such as feature flags, kill-switches, and deferred capabilities.
-
-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
-
-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 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 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 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, 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 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.
-
-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, especially when creating chains of related entities.
-
-## Checks
-
-Run `kb_check` with specific rules during iteration for fast feedback. For normative requirement modeling, include `rules: ["rule-safety", "rule-verifiability", "semantic-completeness", "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.
+## Symbol-First Traceability
 
-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.
+Represent implementation ownership with a `symbol` entity that has
+`sourceFile`, `implements` to the requirement, and `covered_by` to the test.
+Prolog `symbol-coverage` also requires the test to `validates` the requirement
+(or the requirement `verified_by` the test). `covered_by` alone is not
+enough. Do not rely on legacy `// implements REQ-xxx` comments as the
+traceability record.
 
-## Stale or Dirty KB Handling
+## Complete Logical Coverage
 
-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.
+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
 
-| Anti-Pattern | Problem | Remediation |
-|-------------|---------|-------------|
-| Reversed relationship direction | Traceability queries break | Verify direction against the relationship table above |
-| Legacy implements comments | Comments are not durable queryable symbols | Create or update a `symbol` entity and link it to the requirement |
-| Bug-as-flag | `flag` misused for defect tracking | Use `fact` with `fact_kind: observation` or `meta` |
-| Parallel upserts | Lock contention and nondeterminism | Execute `kb_upsert` calls sequentially |
-| Embedded scenarios in reqs | Violates canonical traceability chain | Create separate `req`, `scen`, and `test` entities |
-| 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` |
-| Keeping stale `logic_claims` after prose changes | Makes the manifest disagree with the source ledger | Replace it atomically with exactly the current assertive keys while preserving unrelated metadata |
-| 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 |
+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/src/public/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/src/public/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.

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

@@ -1,44 +1,42 @@
 # 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 -
-```
+Generated from the public `OperationSpec` catalog. CLI JSON and MCP structured
+content use the same `KibiResult` envelope (protocol 1); result data is versioned
+per operation. Effects are authoritative for mutability and adapter annotations.
+
+| MCP tool name | CLI route | Input mode | Mutability | Requires Prolog | Effects | Interface | Result version | Destructive | Retry safety | Open-world | Output schema |
+|---|---|---|---|---|---|---|---|---|---|---|---|
+| `kb_skills_list` | `skills-list` | --input JSON | read | no | local-read | peer; capability-selected | kibi.kb_skills_list.v1 | no | safe | no | yes |
+| `kb_skills_load` | `skills-load` | --input JSON | read | no | local-read | peer; capability-selected | kibi.kb_skills_load.v1 | no | safe | no | yes |
+| `kb_skills_read` | `skills-read` | --input JSON | read | no | local-read | peer; capability-selected | kibi.kb_skills_read.v1 | no | safe | no | yes |
+| `kb_query` | `query` | --input JSON or flags | read | yes | kb-read | peer; capability-selected | kibi.kb_query.v1 | no | safe | no | yes |
+| `kb_search` | `search` | --input JSON or flags | read | yes | kb-read | peer; capability-selected | kibi.kb_search.v1 | no | safe | no | yes |
+| `kb_status` | `status` | --input JSON or flags | read | no | kb-read, workspace-read | peer; capability-selected | kibi.kb_status.v1 | no | safe | no | yes |
+| `kb_find_gaps` | `find-gaps` | --input JSON or flags | read | yes | kb-read | peer; capability-selected | kibi.kb_find_gaps.v1 | no | safe | no | yes |
+| `kb_coverage` | `coverage` | --input JSON or flags | read | yes | kb-read | peer; capability-selected | kibi.kb_coverage.v1 | no | safe | no | yes |
+| `kb_graph` | `graph` | --input JSON or flags | read | yes | kb-read | peer; capability-selected | kibi.kb_graph.v1 | no | safe | no | yes |
+| `kb_semantic_advisor` | `semantic-advisor` | --input JSON | read | no | local-read | peer; capability-selected | kibi.kb_semantic_advisor.v1 | no | safe | no | yes |
+| `kb_model_requirement` | `model-requirement` | --input JSON | read | yes | kb-read | peer; capability-selected | kibi.kb_model_requirement.v1 | no | safe | no | yes |
+| `kb_suggest_predicates` | `suggest-predicates` | --input JSON | read | yes | kb-read | peer; capability-selected | kibi.kb_suggest_predicates.v1 | no | safe | no | yes |
+| `kb_plan_bootstrap` | `plan-bootstrap` | --input JSON | read | no | workspace-read | peer; capability-selected | kibi.kb_plan_bootstrap.v1 | no | safe | no | yes |
+| `kb_validate_upsert` | `validate-upsert` | --input JSON | read | yes | kb-read | peer; capability-selected | kibi.kb_validate_upsert.v1 | no | safe | no | yes |
+| `kb_upsert` | `upsert` | --input JSON | write | yes | kb-write, workspace-write | peer; capability-selected | kibi.kb_upsert.v1 | yes | unsafe | no | yes |
+| `kb_delete` | `delete` | --input JSON | write | yes | kb-write, workspace-write | peer; capability-selected | kibi.kb_delete.v1 | yes | unsafe | no | yes |
+| `kb_check` | `check` | --input JSON or flags | read | yes | kb-read, workspace-read | peer; capability-selected | kibi.kb_check.v1 | no | safe | no | yes |
+| `kb_sparql_remote` | `sparql-remote` | --input JSON | read | no | network-read | peer; capability-selected | kibi.kb_sparql_remote.v1 | no | safe | yes | yes |
+| `kb_compile_intent` | `compile-intent` | --input JSON | read | yes | kb-read, workspace-read | peer; capability-selected | kibi.kb_compile_intent.v1 | no | safe | no | yes |
+| `kb_apply_plan` | `apply-plan` | --input JSON | write | yes | kb-read, kb-write, workspace-read, workspace-write | peer; capability-selected | kibi.kb_apply_plan.v1 | yes | unsafe | no | yes |
+| `kb_ingest_proof` | `ingest-proof` | --input JSON | write | yes | kb-read, kb-write, workspace-read | peer; capability-selected | kibi.kb_ingest_proof.v1 | yes | unsafe | no | yes |
+
+## JSON execution recipe
+
+Use a trusted project-local, non-installing runner. Stdin contains one UTF-8 JSON
+object and stdout contains the versioned result envelope:
 
 ```bash
-echo '{"type":"req","id":"REQ-001","properties":{"title":"Test","status":"open"}}' | npx --no-install kibi upsert --input -
+printf '%s\n' '{"query":"authentication","limit":10}' | npx --no-install kibi search --input -
 ```
 
-```bash
-echo '{"rules":["required-fields","no-dangling-refs"]}' | npx --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.
+`_diagnostic_telemetry` is adapter metadata, not business input. Never copy it
+into entity properties. On `committed_with_repairs`, follow typed required
+`nextActions` and do not retry the original mutation.