kibi-cli 2.19.0 → 2.21.0

package/src/public/operations/discovery-executors.ts

@@ -151,7 +151,10 @@ export type SearchInput = {
 
 export type SearchPayload = {
   readonly results: readonly (SearchMatch | IntentSearchMatch)[];
+  /** Matches in the whole ranking, before `limit` and `offset`. */
   readonly count: number;
+  /** Rows in `results`: the page this call returned. */
+  readonly returned: number;
   readonly truncated?: boolean;
   readonly queryAnalysis?: IntentSearchAnalysis;
   readonly answer?: SearchAnswer;
@@ -772,7 +775,7 @@ export async function executeSearch(
   const {
     query,
     type,
-    limit = 20,
+    limit = 10,
     offset = 0,
     rankingMode = "intent-v1",
     semanticFacets,
@@ -829,6 +832,11 @@ export async function executeSearch(
           : undefined;
       // The structured payload carries every row; the text is a short
       // human-readable digest instead of a second copy of the results.
+      // A top match no requirement owns is said in the digest too, so the
+      // governing list is never read as the top match's requirement.
+      const topUngoverned = answerLayer?.ungoverned.find(
+        (entry) => entry.rank === 1,
+      );
       const text = `${
         intentResult.matches.length === 0
           ? `No intent search results for '${trimmedQuery}' (abstained).`
@@ -837,13 +845,14 @@ export async function executeSearch(
               .map((match) => String(match.entity.id ?? ""))
               .join(
                 ", ",
-              )}${answerLayer ? `. Governing: ${answerLayer.governing.map((req) => req.id).join(", ") || "none found"}` : ""}.`
+              )}${answerLayer ? `. Governing: ${answerLayer.governing.map((req) => req.id).join(", ") || "none found"}` : ""}${topUngoverned ? ` (the top match ${topUngoverned.id} is linked to no requirement)` : ""}.`
       }${storeNote}`;
       return {
         content: [{ type: "text", text }],
         structuredContent: {
           results: await projectMatches(prolog, paginated, fields),
           count: intentResult.matches.length,
+          returned: paginated.length,
           truncated: offset + paginated.length < intentResult.matches.length,
           queryAnalysis: intentResult.analysis,
           ...(answerLayer ? { answer: answerLayer } : {}),
@@ -883,6 +892,7 @@ export async function executeSearch(
       structuredContent: {
         results: await projectMatches(prolog, paginated, fields),
         count: matches.length,
+        returned: paginated.length,
         truncated: offset + paginated.length < matches.length,
         ...branchFields,
       },

package/src/public/operations/migration-plan.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import * as path from "node:path";
+import { planLegacyStorageMigration } from "../../commands/legacy-storage-migration.js";
 import { BRANCH_STORE_NOT_COMPILED } from "../../utils/branch-store.js";
 import { legacyConfigExists } from "../../utils/config.js";
 import { MTIME_SOURCE_REASON_CODES } from "../../utils/content-freshness.js";
@@ -688,6 +689,14 @@ export function buildActionsFromStatus(input: {
   const legacyStorageMigrationRequired = legacyConfigExists(
     input.workspaceRoot,
   );
+  // A legacy cutover that cannot move its files (a destination already
+  // exists, a malformed config) is an operator decision, not an automatic
+  // step that fails when applied and takes the compile with it.
+  const legacyStorage = legacyStorageMigrationRequired
+    ? planLegacyStorageMigration(input.workspaceRoot)
+    : null;
+  const legacyStorageBlocked =
+    legacyStorage !== null && legacyStorage.blockers.length > 0;
   if (storeState === "missing") {
     actions.push(
       migrationAction({
@@ -724,6 +733,8 @@ export function buildActionsFromStatus(input: {
   }
 
   if (configStatus.needsMigration || legacyStorageMigrationRequired) {
+    const operatorOnly =
+      configStatus.status === "newer" || legacyStorageBlocked;
     actions.push(
       migrationAction({
         id: "schema-config-upgrade",
@@ -734,17 +745,34 @@ export function buildActionsFromStatus(input: {
               ? "legacy_storage_migration"
               : "schema_version_upgrade",
         category: "schema",
-        state: configStatus.status === "newer" ? "blocked" : "ready",
-        safety: configStatus.status === "newer" ? "operator" : "automatic",
-        invocation: { kind: "cli", command_argv: ["kibi", "migrate", "--yes"] },
+        state: operatorOnly ? "blocked" : "ready",
+        safety: operatorOnly ? "operator" : "automatic",
+        invocation: legacyStorageBlocked
+          ? {
+              kind: "review",
+              instruction: `The legacy .kb/config.json still names knowledge files outside .kb/ and Kibi cannot move them: ${legacyStorage?.blockers.join(" ")} Keep one copy of each conflicting file (the .kb/ one is what Kibi compiles), remove or git-rm the legacy copy, then run 'kibi migrate --yes' to retire .kb/config.json.`,
+            }
+          : { kind: "cli", command_argv: ["kibi", "migrate", "--yes"] },
         affectedFiles: [
           ".kb/manifest.json",
           ".kb/migrations",
           ".kb/config.json",
+          ...(legacyStorage?.moves.map((move) => move.from) ?? []),
         ],
-        evidence: { configStatus },
+        evidence: {
+          configStatus,
+          ...(legacyStorage === null
+            ? {}
+            : {
+                legacyStorage: {
+                  moves: legacyStorage.moves,
+                  blockers: legacyStorage.blockers,
+                  legacyConfig: legacyStorage.legacyConfig,
+                },
+              }),
+        },
         dependsOn: storeState === "missing" ? ["branch-store-ensure"] : [],
-        autoApplicable: configStatus.status !== "newer",
+        autoApplicable: !operatorOnly,
       }),
     );
   }
@@ -769,12 +797,16 @@ export function buildActionsFromStatus(input: {
           typeof store?.path === "string" ? store.path : ".kb/branches",
         ],
         evidence: { reason: uncompiled },
+        // A blocked schema step waits on an operator; the compile still runs
+        // from the .kb/ sources Kibi already reads.
         dependsOn: actions
-          .map((action) => action.id)
           .filter(
-            (id) =>
-              id === "branch-store-ensure" || id === "schema-config-upgrade",
-          ),
+            (action) =>
+              action.state === "ready" &&
+              (action.id === "branch-store-ensure" ||
+                action.id === "schema-config-upgrade"),
+          )
+          .map((action) => action.id),
         postconditions: [{ branchStore: "compiled" }],
         autoApplicable: true,
       }),

package/src/public/operations/specs/composite.ts

@@ -217,7 +217,7 @@ export const modelSpec = {
   name: "kb_model",
   cliName: "model",
   description:
-    "Turn requirement prose into checkable structure without writing the KB. mode:analyze returns the semantic advisor receipt: the clause ledger, what is grounded, what is ambiguous and suggested modeling (pass clauses for compound prose and optional typed kibi.logic.v1 interpretations). mode:requirement converts one claim (subjectKey, propertyKey, operator, value, or typed logic) into a strict-lane write set and applyPlan. mode:predicates ranks ontology predicate schemas and returns an applicable predicate-fact plan only for reviewed bindings, otherwise an ontology-gap observation. Apply returned plans with kb_upsert.",
+    "Turn requirement prose into checkable structure without writing the KB. mode:analyze returns the semantic advisor receipt: the clause ledger, what is grounded, what is ambiguous and suggested modeling (pass clauses for compound prose and optional typed kibi.logic.v1 interpretations). mode:requirement converts one claim (subjectKey, propertyKey, operator, value, or typed logic) into a strict-lane write set and applyPlan. mode:predicates ranks ontology predicate schemas and returns an applicable predicate-fact plan only for reviewed bindings, otherwise an ontology-gap observation. With requirementId, mode:predicates also returns a hash-bound plan (fact write plus requires_predicate link) for kb_apply_plan, whose contradictionAnalysis is the what-if over the current KB; other returned plans apply with kb_upsert, and kb_upsert dryRun with plannedFacts previews a requirement before its facts exist.",
   businessInputSchema: {
     type: "object",
     required: ["mode", "text"],

package/src/public/operations/specs/discovery.ts

@@ -165,8 +165,9 @@ export const searchSpec = {
       limit: {
         type: "integer",
         minimum: 0,
-        default: 20,
-        description: "Optional max rows to return after ranking. Default: 20.",
+        default: 10,
+        description:
+          "Optional max rows to return after ranking. Default: 10; raise it or page with offset when the answer layer is not enough.",
       },
       offset: {
         type: "integer",

package/src/public/operations/specs/mutation-schemas.ts

@@ -19,22 +19,13 @@ export const ENTITY_TYPES = [
   "fact",
 ] as const;
 
-// An observation or meta fact may quote a claim in claim_text alone: it is a
-// non-grounding review note, so it does not claim the clause's key.
+// A claim_key names the clause in claim_text, so it never travels alone. The
+// reverse is open: Kibi derives a missing claim_key from claim_text on a
+// grounding fact, and an observation or meta fact quotes a claim without one.
+// implements REQ-kibi-review-observation-claim-text-v2
 const CLAIM_PROVENANCE_CONDITIONAL = JSON.parse(`{
-  "if": {
-    "anyOf": [
-      { "required": ["claim_key"] },
-      {
-        "required": ["claim_text"],
-        "not": {
-          "properties": { "fact_kind": { "enum": ["observation", "meta"] } },
-          "required": ["fact_kind"]
-        }
-      }
-    ]
-  },
-  "then": { "required": ["claim_key", "claim_text"] }
+  "if": { "required": ["claim_key"] },
+  "then": { "required": ["claim_text"] }
 }`) as Record<string, unknown>;
 
 export const ENTITY_PROPERTIES_SCHEMA = {
@@ -293,12 +284,12 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       type: "string",
       pattern: "^CLAIM-[A-F0-9]{16}$",
       description:
-        "Stable semantic-advisor key for the atomic prose clause grounded by this fact.",
+        "Stable key of the atomic prose clause grounded by this fact, derived from claim_text. Optional: when omitted, Kibi derives it; when sent, it must equal the derived key.",
     },
     claim_text: {
       type: "string",
       description:
-        "Exact atomic requirement clause represented by this fact, retained for human audit. Requires claim_key, except on an observation or meta fact, which may quote the clause it is about without claim_key.",
+        "Exact atomic requirement clause represented by this fact, retained for human audit. On a grounding fact Kibi derives claim_key from it; an observation or meta fact quotes the clause it is about without a key.",
     },
     predicate_name: {
       type: "string",

package/src/public/operations/specs/upsert.ts

@@ -38,6 +38,21 @@ export const upsertSpec = {
         description:
           "Validate the payload and return schema/modeling errors, a normalized preview and the semantic advisor receipt without writing the KB or workspace. Use it as the preflight before the real write.",
       },
+      plannedFacts: {
+        type: "array",
+        description:
+          "dryRun only. Fact upsert payloads (type, id, properties, optional relationships) that will be written before this payload, typically the applyPlan entries kb_model returned. They are validated in order and staged with the payload, so a requires_predicate or requires_property target that does not exist yet resolves, its claim_key is read from the plan, and the contradiction preview runs against the KB as it would be after the whole batch (result: stagedFacts, whatIf). A conflict the batch would introduce, such as an allow and a deny permission_rule on the same key, is refused as the commit would refuse it. Rejected without dryRun: write the facts first.",
+        items: {
+          type: "object",
+          required: ["type", "id", "properties"],
+          properties: {
+            type: { type: "string", const: "fact" },
+            id: { type: "string", minLength: 1 },
+            properties: { type: "object" },
+            relationships: RELATIONSHIPS_SCHEMA,
+          },
+        },
+      },
       document: {
         type: "object",
         additionalProperties: false,

package/src/public/schemas/entity.ts

@@ -42,19 +42,8 @@ type VerificationPerspective = "internal" | "consumer";
 
 const factConditionals = JSON.parse(`[
   {
-    "if": {
-      "anyOf": [
-        { "required": ["claim_key"] },
-        {
-          "required": ["claim_text"],
-          "not": {
-            "properties": { "fact_kind": { "enum": ["observation", "meta"] } },
-            "required": ["fact_kind"]
-          }
-        }
-      ]
-    },
-    "then": { "required": ["claim_key", "claim_text"] }
+    "if": { "required": ["claim_key"] },
+    "then": { "required": ["claim_text"] }
   },
   {
     "if": {

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.15.0
+version: 2.15.3
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -82,6 +82,41 @@ different workspace than the one you asked for; its `detail.reason` says why.
 Use the CLI from your working directory instead: `npx --no-install kibi ...`
 runs where you are and needs no `workspaceRoot`.
 
+## Reading a hook snippet
+
+On hosts where Kibi hooks are installed, a short block
+arrives before you read or edit a file whose symbols are linked to
+requirements. It is projected from `.kb/symbols.yaml`, not from the store, so
+it is a pointer to the knowledge, never proof. Each line answers one question:
+
+- `Kibi knowledge for <path> (symbol manifest):` and the `- REQ-… — <symbol
+  titles>` rows: the requirements the file's symbols implement, lead
+  requirement first. Read the lead requirement with `kb_query({id})` before
+  changing behavior.
+- `REQ-… must keep true: FACT-…` (edit only): the ground facts the lead
+  requirement requires. An edit that breaks one of them is a requirement
+  change: supersede and remodel the requirement, do not code around the fact.
+- `Decision: ADR-…` (edit only): the decision behind the lead requirement.
+- `Covered by: TEST-…` and `Test code for: …`: the tests that prove the
+  file's symbols; run or update them with the edit.
+- `The edit is inside <symbol>, which implements REQ-…`: the symbol the edit
+  lands in.
+- `Next layer: …`: the exact `kb_query` and `kb_search(... sourceLocations)`
+  calls that return the full detail.
+- The `kb_check({sourceFiles:[…], includeImpactDiagnostics:true,
+  includeWorkingTreeDiff:true})` line (edit only): run it after the edit. The
+  Stop hook reminds you once per session of files edited without it.
+
+A file already shown this session gets only the one-line `Kibi: this edit to
+<path> is inside <symbol>` update; the facts and tests from its first snippet
+still apply. `Kibi: no symbol in <path> is linked to a requirement yet` means
+the file is unowned: find the governing requirement with `kb_search` and
+`sourceLocations`, then link a symbol to it with `implements` through
+`kb_upsert`. Without a readable manifest (`Kibi: the hook could not read
+.kb/symbols.yaml`) snippets are off for this session; `kb_query({sourceFile})`
+still answers and `kibi sync` regenerates the manifest. The search tip and the
+`.kb/` note appear once per session and need no action.
+
 ## Safe workflow
 
 1. Always discover before you mutate: start with `kb_search`, then exact-filter with `kb_query`. Use
@@ -334,6 +369,8 @@ For each relational clause, call `kb_model` with `mode: "predicates"`, that clau
 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`.
+`claim_key` is derived from `claim_text`, so a ground fact may send the exact
+clause alone and Kibi fills the key in; a sent key must equal the derived one.
 Use `kb_model` with `mode: "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.

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

@@ -6,7 +6,7 @@ Requirement prose remains the human-readable source. Facts add queryable semanti
 
 Logical coverage is clause-based, not entity-based. Give `kb_model` (`mode: "analyze"`) 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;
+- put the exact clause as `claim_text` on its ground fact, with the returned stable key as `claim_key` or none (Kibi derives a missing key; a sent key must match);
 - add the key to the exact current `logic_claims` set, removing only stale keys whose propositions no longer exist in the source;
 - link it through exactly one `requires_property` for `property_value`, one `requires_predicate` for `predicate`, or one `requires_rule` for a safe `rule` fact;
 - leave ambiguity and ontology gaps visibly unresolved—observations do not satisfy `logic-coverage`.
@@ -68,14 +68,16 @@ id: FACT-SUSPENDED-PUBLISH-DENIED
 status: active
 fact_kind: predicate
 predicate_name: permission_rule
-predicate_args: [suspended_user, publish, articles, deny]
+predicate_args: [suspended_user, publish, article, deny]
 polarity: deny
-canonical_key: permission_rule(suspended_user,publish,articles,deny)
+canonical_key: permission_rule(suspended_user,publish,article,deny)
 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 }
 ```
 
+Inferred bindings drop the article and singularise the resource (`articles` becomes `article`, `any analysis request` and `analysis requests` both become `analysis_request`), so an allow and a deny on the same actor, action and resource share one key. Grants read the same as `allowed`: `may`, `can`, `is allowed to`, `are permitted to`, `must be able to`, `are able to`, `have permission to` and `are entitled to` all select `permission_rule` with `polarity: assert`.
+
 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.

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

@@ -126,8 +126,8 @@ diagnostics (`symbol_semantic_review_needed`).
    `requires_predicate`.
 3. Scalar placement/alignment/order clauses: `kb_model` (`mode: "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.
+4. Preserve `claim_key` / `claim_text` (a missing key is derived from the
+   text); merge every key into the requirement `logic_claims` manifest.
 5. `kb_upsert` with `dryRun: true`, create endpoints first, then sequential `kb_upsert`.
 6. `kb_check` with `logic-coverage`, `predicate-verifiability`, `domain-contradictions`,
    then a final unfiltered `kb_check`.

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

@@ -203,7 +203,7 @@ Optional per-project workflow for recording what the screen should look like. No
 2. Run `kb_model` with `mode: "analyze"` on the description; audit or supply `clauses`.
 3. For relational layout clauses ("X must remain visually aligned with Y"), call `kb_model` with `mode: "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` with `mode: "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.
+5. Preserve `claim_key` / `claim_text` on every ground fact (a missing `claim_key` is derived from `claim_text`) 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_upsert` with `dryRun: true`, create endpoints first, then sequential `kb_upsert`. Run `kb_check` with `logic-coverage`, `predicate-verifiability`, and `domain-contradictions`, then a final unfiltered `kb_check`.
 

package/src/schemas/entity.schema.json

@@ -1675,35 +1675,12 @@
     },
     {
       "if": {
-        "anyOf": [
-          {
-            "required": [
-              "claim_key"
-            ]
-          },
-          {
-            "required": [
-              "claim_text"
-            ],
-            "not": {
-              "properties": {
-                "fact_kind": {
-                  "enum": [
-                    "observation",
-                    "meta"
-                  ]
-                }
-              },
-              "required": [
-                "fact_kind"
-              ]
-            }
-          }
+        "required": [
+          "claim_key"
         ]
       },
       "then": {
         "required": [
-          "claim_key",
           "claim_text"
         ]
       }