kibi-cli 2.17.0 → 2.19.0

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

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import * as path from "node:path";
 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";
 import { readKbManifestStatus } from "../../utils/kb-manifest.js";
 import {
   getSchemaVersionStatus,
@@ -616,6 +617,9 @@ function readLegacySchemaVersion(
 }
 
 // implements REQ-agent-guided-migration-orchestration
+/** Migration action code of the automatic recompile of changed sources. */
+export const FRESHNESS_RESYNC = "freshness_resync";
+
 export function buildActionsFromStatus(input: {
   workspaceRoot: string;
   branchAttachment?: Readonly<Record<string, unknown>>;
@@ -777,10 +781,50 @@ export function buildActionsFromStatus(input: {
     );
   }
 
+  // implements REQ-cli-status-pre-first-sync
+  // Sources whose content changed since the last compilation (kb_status has
+  // already dropped mtime-only reasons) are fixed by recompiling them: one
+  // automatic `kibi sync`, not a review per file. An uncompiled store is
+  // compiled by the step above, which also covers these files.
+  const resyncReasons = (input.staleReasons ?? []).filter(
+    (reason) =>
+      typeof reason.code === "string" &&
+      MTIME_SOURCE_REASON_CODES.has(reason.code),
+  );
+  if (resyncReasons.length > 0 && uncompiled === undefined) {
+    actions.push(
+      migrationAction({
+        id: "freshness-resync",
+        code: FRESHNESS_RESYNC,
+        category: "freshness",
+        safety: "automatic",
+        invocation: { kind: "cli", command_argv: ["kibi", "sync"] },
+        affectedFiles: [
+          ...new Set(
+            resyncReasons.flatMap((reason) =>
+              typeof reason.path === "string" ? [reason.path] : [],
+            ),
+          ),
+        ].sort(),
+        evidence: { reasons: resyncReasons },
+        dependsOn: actions
+          .map((action) => action.id)
+          .filter(
+            (id) =>
+              id === "branch-store-ensure" || id === "schema-config-upgrade",
+          ),
+        postconditions: [{ syncState: "fresh" }],
+        autoApplicable: true,
+      }),
+    );
+  }
+
   for (const reason of input.staleReasons ?? []) {
     const code = typeof reason.code === "string" ? reason.code : "stale_source";
     // Planned above as an automatic compile step, not a review.
     if (code === BRANCH_STORE_NOT_COMPILED) continue;
+    // Planned above as one automatic resync (or covered by the compile).
+    if (MTIME_SOURCE_REASON_CODES.has(code)) continue;
     const file = typeof reason.path === "string" ? reason.path : "";
     actions.push(
       migrationAction({

package/src/public/operations/source-relationship-parity.ts

@@ -2,6 +2,7 @@ import { execFileSync } from "node:child_process";
 import path from "node:path";
 import { discoverSourceFiles } from "../../commands/sync/discovery.js";
 import { processExtractions } from "../../commands/sync/extraction.js";
+import { findUntrackedDocumentMatches } from "../../commands/sync/untracked-targets.js";
 import type { ExtractedRelationship } from "../../extractors/markdown.js";
 import { RELATIONSHIP_TYPES } from "../../operations/mutation/relationships.js";
 import { parseListOfLists, parsePrologValue } from "../../prolog/codec.js";
@@ -234,8 +235,64 @@ export async function collectSourceRelationshipParityViolations(
     });
   }
 
-  return compareRelationshipParity(
-    authored,
-    await compiledRelationships(prolog),
+  return explainUntrackedEndpoints(
+    workspaceRoot,
+    compareRelationshipParity(authored, await compiledRelationships(prolog)),
   );
 }
+
+/**
+ * An authored relationship is missing from the compiled KB most often
+ * because an endpoint is declared in a file sync cannot see: one Git does not
+ * track and no pending-source receipt covers (for example a `.kb/symbols.yaml`
+ * that `kibi init` created and kb_upsert appended to before receipts covered
+ * existing untracked files). Name that file and the fix.
+ */
+// implements REQ-kibi-source-relationship-parity
+function explainUntrackedEndpoints(
+  workspaceRoot: string,
+  violations: Violation[],
+): Violation[] {
+  const endpoints = new Set<string>();
+  for (const violation of violations) {
+    const relationship = authoredToCompiledRelationship(violation);
+    if (relationship === null) continue;
+    endpoints.add(relationship.from);
+    endpoints.add(relationship.to);
+  }
+  if (endpoints.size === 0) return violations;
+  const untracked = findUntrackedDocumentMatches(workspaceRoot, [...endpoints]);
+  if (untracked.size === 0) return violations;
+  return violations.map((violation) => {
+    const relationship = authoredToCompiledRelationship(violation);
+    if (relationship === null) return violation;
+    const sources = [relationship.from, relationship.to].flatMap((id) => {
+      const file = untracked.get(id);
+      return file === undefined ? [] : [{ entityId: id, file }];
+    });
+    if (sources.length === 0) return violation;
+    const files = [...new Set(sources.map((source) => source.file))];
+    return {
+      ...violation,
+      suggestion: `${sources.map((source) => source.entityId).join(" and ")} ${sources.length === 1 ? "is" : "are"} declared in ${files.join(", ")}, which Git does not track and no pending-source receipt covers, so sync never compiles it. Run 'git add ${files.join(" ")}' (staging is enough) or rewrite the entity with kb_upsert, then run kibi sync and rerun kb_check.`,
+      evidence: {
+        ...(violation.evidence ?? {}),
+        untrackedSources: sources,
+      },
+    };
+  });
+}
+
+function authoredToCompiledRelationship(
+  violation: Violation,
+): { from: string; to: string } | null {
+  const evidence = violation.evidence as
+    | { direction?: unknown; relationship?: { from?: unknown; to?: unknown } }
+    | undefined;
+  if (evidence?.direction !== "authored_to_compiled") return null;
+  const from = evidence.relationship?.from;
+  const to = evidence.relationship?.to;
+  return typeof from === "string" && typeof to === "string"
+    ? { from, to }
+    : null;
+}

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

@@ -24,11 +24,22 @@ const ENTITY_TYPES = [
   "fact",
 ] as const;
 
+const FACT_KINDS = [
+  "subject",
+  "property_value",
+  "predicate",
+  "predicate_schema",
+  "observation",
+  "meta",
+  "rule",
+  "rule_schema",
+] as const;
+
 export const querySpec = {
   name: "kb_query",
   cliName: "query",
   description:
-    "Read entities from the KB with filters. Use for discovery and lookup before edits. Do not use for writes. No mutation side effects. Tags filter by metadata tags only, not entity IDs.",
+    "Read entities from the KB with exact filters, or ask typed fact questions. Use for lookup by id, type, tags or sourceFile, and for precise questions about modeled facts: predicate facts by name with named arguments (predicate + where), property facts of a subject (subjectKey + propertyKey), or the catalog of facts of one kind (factKind; 'predicate_schema' lists the predicates you can ask about with their argument names and constants). Typed answers return matching fact rows plus factQuery: the schema used, distinct counts, values that do exist when nothing matched, warnings about the question and the next call to make. Read-only. Tags filter by metadata tags only, not entity IDs.",
   businessInputSchema: {
     type: "object",
     properties: {
@@ -54,6 +65,61 @@ export const querySpec = {
         description:
           "Optional source-file substring filter. Example: 'src/auth/login.ts'. Uses KB source linkage, not file-system scanning.",
       },
+      factKind: {
+        type: "string",
+        enum: FACT_KINDS,
+        description:
+          "Typed fact filter: list facts of one kind with their typed fields. 'predicate_schema' returns the catalog of askable predicates (argument names, constants, fact counts). Example: 'predicate_schema'.",
+      },
+      predicate: {
+        type: "string",
+        description:
+          "Typed fact filter: predicate name to ask about, e.g. 'has_role' or 'permission_rule'. Combine with where for named arguments. Returns every stored fact of that predicate with its arguments, polarity and allow/deny effect.",
+      },
+      namespace: {
+        type: "string",
+        description:
+          "Optional predicate namespace when the same name exists in several. Default: any namespace.",
+      },
+      where: {
+        type: "object",
+        additionalProperties: { type: "string" },
+        description:
+          "Named argument values for predicate, order-free, using the argument names from the predicate's schema. Example: {actor: 'admin', decision: 'allow'}. An unknown name returns a warning with the declared names; no match returns the values that do exist.",
+      },
+      args: {
+        type: "array",
+        items: { type: ["string", "null"] },
+        description:
+          "Positional argument values for predicate when it has no schema; null matches any value. Example: ['admin', null, null, 'allow']. Prefer where.",
+      },
+      polarity: {
+        type: "string",
+        enum: ["assert", "deny"],
+        description:
+          "Optional polarity filter for predicate facts. Default: both.",
+      },
+      scope: {
+        type: "string",
+        enum: ["all", "current_requirements"],
+        description:
+          "Optional: 'current_requirements' keeps only facts a current (not superseded or retired) requirement requires.",
+      },
+      distinct: {
+        type: "string",
+        description:
+          "Optional argument name to count distinct values of across the matching predicate facts, e.g. distinct: 'role' with predicate 'has_role' and where {user: 'alice'} answers how many roles alice has.",
+      },
+      subjectKey: {
+        type: "string",
+        description:
+          "Typed fact filter: dotted subject key whose property facts to list, e.g. 'user.role_assignment'. Combine with propertyKey for one property.",
+      },
+      propertyKey: {
+        type: "string",
+        description:
+          "Optional property key under subjectKey, e.g. 'max_roles'. Returns operator, value and unit of each fact.",
+      },
       limit: {
         type: "number",
         default: 100,

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.13.0
+version: 2.15.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -237,7 +237,11 @@ authored. Each one is the order the write path accepts.
    fact, `requires_predicate` to `relationshipTarget` and `specified_by` to
    its scenario: `specified_by` (req → scenario) is sent in the
    requirement's write, never in the scenario's, so create the scenario
-   first. A
+   first, with `assumes` links (scenario → `property_value` fact, sent in
+   the scenario's own write) to the values its outcome relies on. Set
+   `expects` only on a scenario that has `assumes` links; `expects: success`
+   without them only yields `scenario-feasibility-unknown` ("assumes
+   nothing"). 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`
@@ -249,7 +253,12 @@ authored. Each one is the order the write path accepts.
    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
+   the old one, then set the old one to `status: closed`. Its scenario
+   follows the same rule as in recipe 1: create the new scenario (with
+   `assumes` to the `property_value` facts it relies on, and `expects` only
+   when it has them) before the `-v2` write that sends `specified_by`, then
+   re-point the old scenario (its `assumes` go in its own write) or close
+   it. 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,
@@ -400,6 +409,14 @@ Prolog `symbol-coverage` also requires the test to `validates` the requirement
 enough. Do not rely on legacy `// implements REQ-<area>-<behavior>` comments as the
 traceability record.
 
+Set the symbol's `title` to the behavioral member the extractor can locate in
+`sourceFile`: `ClassName.methodName`, an exported function, or a class, not a
+file or module name. A traceability link (`implements`, `covered_by`, …) from
+a symbol whose `title` names no such member is refused by the granularity gate
+when the file already has granular behavioral symbols, unless the symbol sets
+`granularity_reason` to `config-artifact`, `module-level-behavior`,
+`extractor-miss`, `legacy-link` or `test-suite`.
+
 ## Complete Logical Coverage
 
 Decompose all atomic normative clauses into `claim_key`/`claim_text` entries in

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

@@ -97,6 +97,29 @@ Cosmetic edits (descriptions, labels) never stale proof. Execution-relevant
 edits (command, artifact, targets, options, bindings, contract) change the
 effective fingerprint and do.
 
+## What counts toward proofProven
+
+A requirement is proven only by its scenarios' tests, and a scenario test
+counts only when it is an **end-to-end** test with a valid, fresh, passing
+receipt for the current snapshot.
+
+- The scope comes from the test entity's `verification_scope`
+  (`end_to_end`, `integration`, `unit`), never from the integration id or the
+  producer. Without `verification_scope`, a test tagged `e2e` (or whose
+  `source` path contains `e2e`) counts as end-to-end; anything else is
+  `unknown` scope.
+- A `unit` or `integration` receipt is still recorded on the test entity, but
+  it does not move `proofProven` for a behavioural requirement: the
+  requirement keeps the `missing_passing_e2e` gap in `proofGaps`. The one
+  exception is a scenario whose specifying requirements are all grounded only
+  in component-scope UI predicates (`ui_pattern`, `same_pattern`,
+  `pattern_marker`); a unit or integration test that renders the component
+  may prove it.
+- `coverage_depth` (`kb_coverage`, `kb_find_gaps`) follows the test's
+  authored `status` (`passing`) and scope, not its receipts: a passing
+  receipt does not change it, and a `passing` status without a fresh receipt
+  proves nothing.
+
 ## Attempt semantics (factual, never optimistic)
 
 - `attempts: {status: "complete", entries: [...]}` — known history; the