kibi-cli 2.13.0 → 2.15.0

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

@@ -2,7 +2,7 @@
 id: kibi-usage
 name: Kibi Usage
 description: Use Kibi's source-first, exact-Git, migration-aware, proof-aware operations safely across MCP or the trusted local CLI, including partial completion repair.
-version: 2.9.0
+version: 2.11.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -209,6 +209,71 @@ An interrupted plan is settled by the next `kb_apply_plan`, `kb_upsert`, or
 re-apply the original plan. On a detached HEAD, reads answer from a read-only
 snapshot and writes are refused; check out a branch before mutating.
 
+## Second-agent edits
+
+Recipes for an agent changing a knowledge base another agent or person
+authored. Each one is the order the write path accepts.
+
+1. **New strict requirement with a predicate grounding.** `kb_model` mode
+   `analyze` with the complete prose; copy `inventory_contract` into
+   `semantic_inventory_version`, `semantic_source_field` and
+   `semantic_source_hash`, the prose into `semantic_text`, `propositions`
+   into `semantic_inventory` and the assertive `claim_key`s into
+   `logic_claims`. `kb_model` mode `predicates` per clause; `kb_upsert` the
+   returned `applyPlan` fact first (it carries the clause's `claim_key`).
+   Then write the requirement in one `kb_upsert` with the ledger (that
+   clause `status: modeled`), a sectioned `document.body`, `constrains` to
+   the subject fact and `requires_predicate` to `relationshipTarget`. A
+   `modeled` entry and its grounding link must arrive in the same write
+   (`modeled semantic_inventory entries (n) must equal logical grounding
+   relationships (m)`); a clause not grounded yet stays `status: missing`
+   and is switched to `modeled` together with its link later. A partial
+   `{title, status}` upsert (plus relationships) is enough only for an
+   existing entity, whose stored ledger Kibi keeps.
+2. **Changing the text of a grounded requirement.** New prose means new
+   claim keys, so a bare rewrite is refused with `modeled proposition
+   claim_keys must match logical grounding target claim_keys exactly`.
+   Prefer supersession for a change of meaning: analyze the new prose,
+   write its facts, write the new requirement (`-v2`) with `supersedes` to
+   the old one, then set the old one to `status: closed`. For a wording fix
+   that keeps the meaning, re-ground in place: analyze the new prose,
+   `kb_upsert` each grounding fact with the new `claim_key`/`claim_text`
+   (same fact id), then `kb_upsert` the requirement with the new ledger,
+   `semantic_text` and the same grounding links in one write. The requirement
+   write checks the targets' stored claim keys, so the facts go first;
+   between the two writes `kb_check` reports the requirement until the
+   second lands.
+3. **Deleting authored entities.** `kb_delete` on an authored entity that
+   is not a requirement (scenario, test, fact, ADR, …) returns a hash-bound
+   `kibi.entity-deletion-plan.v1` in `deletionPlan`; apply it unchanged with
+   `kb_apply_plan` (`plan` plus `approvedPlanHash: plan.planHash`). For an
+   authored requirement the plan carries `supersessionRequired: true` and
+   `kb_apply_plan` refuses it (`REQUIREMENT_SUPERSESSION_REQUIRED`): Kibi
+   never deletes an authored requirement. Evolve it instead with a new
+   requirement linked by `supersedes` and close the old one, or, for an
+   agent-origin requirement nobody approved and nothing links to, upsert it
+   with `status: closed` (keep its `title`); it stays on disk as history. A
+   person may remove the file in Git and run `kibi sync`; agents do not edit
+   `.kb/` directly.
+4. **After a commit-time refusal** (`Contradiction detected …
+   (stage=contradiction_check)`, strict-lane pairing, proposition-complete
+   ingestion): the result is `status: error` and nothing was written. The
+   authored file, the relationship shards, the pending-source receipt of an
+   untracked file and the file times are restored, so `kb_check` (including
+   `source-relationship-parity`) stays clean and `kb_status` stays `fresh`;
+   verify both, fix the cause (supersede, pair the lane, re-ground), and
+   resend the whole payload. A `committed_with_repairs` result is the
+   opposite case: the commit stands and only its repair actions are run.
+5. **What `dryRun: true` does and does not check.** It runs every
+   pre-commit validation and, for a `req`, the commit-time contradiction
+   check against a staged, rolled-back copy of the store, so `valid: true`
+   means the commit would accept the payload as far as the store can tell.
+   It writes nothing, so it cannot report what only a write reveals:
+   `DOCUMENT_PATH_REQUIRED` for a new entity with no single writable target,
+   filesystem, lock and receipt failures, a concurrent writer, or
+   `kb_check`-only rules such as `logic-coverage` and `scenario-feasibility`
+   (`entity-context-missing` is returned as a warning).
+
 ## Origin and approvals
 
 Entities record `origin` (`kind`: `human`, `agent`, `migration`, or `import`,
@@ -264,7 +329,17 @@ subject. A schema without a `subject` argument (`permission_rule`) records
 that key as the planned fact's `subject_key` instead; when the requirement
 constrains several subjects, an unbound `subject_key` asks you to pass
 `subjectHint` with one of them. A participant (`actor`, `resource`, entity)
-is a short noun, never a clause of the claim. Bind them
+is a short noun, never a clause of the claim, and an `actor`, `role` or
+`owner` is never the requirement's subject key: the planned fact already
+carries that key as `subject_key`, so `actor = <subject key>` stays unbound
+with a reason. When the claim names no participant for such an argument (the
+value is empty, the subject key or a clause that opens with a gerund such as
+"Discarding a draft while …", and none of the schema's constants or example
+values occurs in the claim), the schema does
+not fit the claim and Kibi answers `record_ontology_gap` with the gap
+observation in `applyPlan`; the candidate stays listed as `incomplete` with
+its `bindingHints`. Write the observation instead of inventing a participant.
+For every other unbound argument, bind it
 from the claim's own words and call again with the same `text` and
 `requirementId`, plus `schemaId` and `argumentBindings` keyed by
 `argument_names` (reuse `argument_constants` values when the schema has them).
@@ -283,9 +358,10 @@ grounds the claim (for example a bootstrap `requires_property` fact); the action
 still names the predicate state. `replace_grounding` means a predicate fits but
 a second grounding link would fail, so keep the existing link or apply the
 `replacementPlan` steps unchanged, in order and back to back (predicate fact,
-`kb_delete` of the old link, requirement link; `kb_check` reports
-`logic-coverage` only between the last two; on a failed last step apply
-`rollback`); `provide_argument_bindings` and `record_ontology_gap` mean
+`kb_delete` of the old link, requirement link; between the last two `kb_check`
+reports both `logic-coverage` and `strict-req-fact-pairing` for the
+requirement, as `expected.kbCheckAfterStep` states; run `kb_check` after the
+last step and apply `rollback` if it is not clean); `provide_argument_bindings` and `record_ontology_gap` mean
 the same as for an ungrounded claim, and the gap observation is not a grounding
 link, so write it exactly as returned (tags, `claim_text`, `document.body`, no
 `claim_key`, no relationships). Record an ontology gap only when no returned schema fits the

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

@@ -1,7 +1,10 @@
 # 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.
+silently drift from the spec. Non-UI projects skip it entirely. Without the experimental
+`kibi-plugin-ui` no check rule requires it; with that plugin active, `kb_check` blocks
+components that lack a design requirement (`policy-ownership`) and implementations that
+lose their pattern markers (`policy-markers`).
 
 ## Three layers
 
@@ -13,12 +16,48 @@ silently drift from the spec. Non-UI projects skip it entirely; no check rule re
    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.
+   aligned with Y" (relation `aligned_with`); `ui_pattern`, `same_pattern` and
+   `pattern_marker` cover patterns (below); `ui_container(subject, size, overflow)` covers
+   "a half-page panel that scrolls". 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.
 
+## Patterns and variants
+
+Name the visual pattern a concept uses, and which variants must share it, so a rewrite to a
+different pattern (a line-and-dots timeline redone as cards) is a visible contradiction
+instead of a silent drift. All three predicates are built in:
+
+- `ui_pattern(subject, pattern)`: `ui_pattern(activity_feed, line_dots_timeline)`.
+- `same_pattern(subject, variant, other_variant)`: `same_pattern(activity_feed, editor_view, read_only_view)`.
+- `pattern_marker(pattern, marker)`: `pattern_marker(line_dots_timeline, timeline_dot)`; the
+  marker is a literal class name or test id every implementation of the pattern contains.
+
+Link the first two from the requirement with `requires_predicate`. Marker facts belong to
+the pattern, not to one requirement, so link them from the requirement that introduced the
+pattern or leave them standalone. With `kibi-plugin-ui` active, every component that
+implements a requirement naming a `ui_pattern` must contain each marker of that pattern in
+its source or its `.html` template. A component with no design constraint (a
+layout-free wrapper) carries the tag `review:ui-unconstrained` instead of a requirement.
+
+A requirement grounded only in `ui_pattern`, `same_pattern` and `pattern_marker` is proved
+by component tests: a test with `verification_scope: unit` or `integration` and a fresh
+passing receipt satisfies its scenarios. Write one component test per variant named in
+`same_pattern`; that is what catches a divergent branch inside one template, which the
+static marker check cannot see. Adding any other fact (`ui_container`, a property) brings
+back the end-to-end requirement.
+
+### Capturing the inventory
+
+When the plugin is first enabled on an existing UI, list the patterns the code already
+uses per screen, ask the human which is intended wherever two variants of one concept
+differ, and record each answer as a requirement. Record a divergence the human has not
+decided as an `observation` fact tagged `review:ui-divergence`, citing both files, rather
+than guessing which variant is right. Colours, spacing and component-library choices
+(which scrollbar component to use) belong in a linter, not here.
+
 ## Button position
 
 ```yaml