kibi-cli 2.17.0 → 2.18.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/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.14.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,

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