kibi-cli 2.17.0 → 2.18.0

package/dist/public/operations/source-relationship-parity.js

@@ -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 { RELATIONSHIP_TYPES } from "../../operations/mutation/relationships.js";
 import { parseListOfLists, parsePrologValue } from "../../prolog/codec.js";
 import { readAllShards } from "../../relationships/shards.js";
@@ -173,5 +174,58 @@ export async function collectSourceRelationshipParityViolations(workspaceRoot, p
             source: ".kb/relationships",
         });
     }
-    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, violations) {
+    const endpoints = new Set();
+    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) {
+    const evidence = violation.evidence;
+    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/dist/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/dist/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

package/dist/utils/branch-store.d.ts

@@ -21,6 +21,14 @@ export declare function inspectBranchStore(workspaceRoot: string, branch: string
  * auto-heal; the reason exists so operators see the state before it bites.
  */
 export declare function storeLockJournalReason(storePath: string): Record<string, unknown> | null;
+/**
+ * An informational notice that this branch store's lock was taken over from
+ * a dead holder. The takeover itself is safe and automatic; it is reported
+ * because it means an engine or prove run crashed or was killed while it
+ * held the store, which nothing else shows once the new holder rewrites the
+ * ownership journal. Visible for STORE_LOCK_TAKEOVER_VISIBLE_MS.
+ */
+export declare function storeLockTakeoverReason(storePath: string, now?: Date): Record<string, unknown> | null;
 export declare function branchStoreReason(inspection: BranchStoreInspection): Record<string, unknown> | null;
 /**
  * The number of authored source files under `.kb/`: entity Markdown in the

package/dist/utils/branch-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"branch-store.d.ts","sourceRoot":"","sources":["../../src/utils/branch-store.ts"],"names":[],"mappings":"AAwBA,mEAAmE;AACnE,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AACrE,yCAAyC;AACzC,eAAO,MAAM,8BAA8B,8BAA8B,CAAC;AAE1E,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,SAAS,GACT,YAAY,GACZ,YAAY,CAAC;AAEjB,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,KAAK,EAAE,gBAAgB,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAAC,CAAC;AAEH;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GACb,qBAAqB,CA0GvB;AAED;;;;GAIG;AAEH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAiBhC;AAED,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,qBAAqB,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAWhC;AA6BD;;;;GAIG;AAEH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAOpE;AAED,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC,CAAC;AAEH;;;;;;GAMG;AAEH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,qBAAqB,GAChC,sBAAsB,CAwBxB;AAkBD;;;;;;GAMG;AAEH,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,qBAAqB,EACjC,MAAM,EAAE,MAAM,GACb,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAwBhC"}
+{"version":3,"file":"branch-store.d.ts","sourceRoot":"","sources":["../../src/utils/branch-store.ts"],"names":[],"mappings":"AA0BA,mEAAmE;AACnE,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AACrE,yCAAyC;AACzC,eAAO,MAAM,8BAA8B,8BAA8B,CAAC;AAE1E,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,SAAS,GACT,YAAY,GACZ,YAAY,CAAC;AAEjB,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,KAAK,EAAE,gBAAgB,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAAC,CAAC;AAEH;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GACb,qBAAqB,CA0GvB;AAED;;;;GAIG;AAEH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAiBhC;AAED;;;;;;GAMG;AAEH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,IAAiB,GACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAehC;AAED,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,qBAAqB,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAWhC;AA6BD;;;;GAIG;AAEH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAOpE;AAED,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC,CAAC;AAEH;;;;;;GAMG;AAEH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,qBAAqB,GAChC,sBAAsB,CAwBxB;AAkBD;;;;;;GAMG;AAEH,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,qBAAqB,EACjC,MAAM,EAAE,MAAM,GACb,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAwBhC"}

package/dist/utils/branch-store.js

@@ -4,7 +4,7 @@
 */
 import { existsSync, readFileSync, readdirSync, statSync, } from "node:fs";
 import * as path from "node:path";
-import { classifyStoreLockHolder, readStoreLockOwner, } from "../prolog/store-lock.js";
+import { STORE_LOCK_TAKEOVER_VISIBLE_MS, classifyStoreLockHolder, readStoreLockOwner, readStoreLockTakeover, } from "../prolog/store-lock.js";
 import { branchStoreManifestMatches, branchStorePath, legacyBranchStorePath, } from "./branch-store-locator.js";
 import { ENTITY_LANES, KB_ROOT } from "./kb-paths.js";
 /** Stale-reason code of a branch store that was never compiled. */
@@ -147,6 +147,32 @@ export function storeLockJournalReason(storePath) {
         },
     };
 }
+/**
+ * An informational notice that this branch store's lock was taken over from
+ * a dead holder. The takeover itself is safe and automatic; it is reported
+ * because it means an engine or prove run crashed or was killed while it
+ * held the store, which nothing else shows once the new holder rewrites the
+ * ownership journal. Visible for STORE_LOCK_TAKEOVER_VISIBLE_MS.
+ */
+// implements REQ-core-journaled-engine-persistence
+export function storeLockTakeoverReason(storePath, now = new Date()) {
+    const record = readStoreLockTakeover(storePath);
+    if (record === null)
+        return null;
+    const age = now.getTime() - Date.parse(record.at);
+    if (age < 0 || age > STORE_LOCK_TAKEOVER_VISIBLE_MS)
+        return null;
+    return {
+        code: "store_lock_taken_over",
+        path: record.path,
+        entityIds: [],
+        blocking: false,
+        brokenPid: record.brokenPid,
+        reason: record.reason,
+        at: record.at,
+        detail: `Kibi broke a stale branch-store lock at ${record.at} (${record.reason || "holder no longer running"}) and reattached. Nothing needs repair; a holder that died while it held the store usually means an engine or kibi prove run crashed or was killed.`,
+    };
+}
 export function branchStoreReason(inspection) {
     if (inspection.state === "healthy")
         return null;

package/dist/utils/content-freshness.d.ts

@@ -0,0 +1,13 @@
+/** Stale-reason codes that compare file times only. */
+export declare const MTIME_SOURCE_REASON_CODES: ReadonlySet<string>;
+type Reason = Readonly<Record<string, unknown>>;
+/**
+ * Drop mtime-only stale reasons whose file content provably matches what the
+ * store compiled. Reasons without such evidence are kept.
+ */
+export declare function confirmSourceNewerReasons(workspaceRoot: string, storePath: string, reasons: readonly Reason[]): {
+    kept: Reason[];
+    dropped: Reason[];
+};
+export {};
+//# sourceMappingURL=content-freshness.d.ts.map

package/dist/utils/content-freshness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-freshness.d.ts","sourceRoot":"","sources":["../../src/utils/content-freshness.ts"],"names":[],"mappings":"AAYA,uDAAuD;AACvD,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAIxD,CAAC;AAEH,KAAK,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AA6IhD;;;GAGG;AAEH,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAkBvC"}

package/dist/utils/content-freshness.js

@@ -0,0 +1,161 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+*/
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+import { load as parseYAML } from "js-yaml";
+import { hashManifestWithCoordinates } from "../commands/sync/cache.js";
+import { isSymbolsManifestPath } from "./kb-paths.js";
+/** Stale-reason codes that compare file times only. */
+export const MTIME_SOURCE_REASON_CODES = new Set([
+    "indexed_source_newer",
+    "knowledge_source_newer",
+    "documentation_source_newer",
+]);
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function readJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * Content evidence recorded by the last compilation: the store's sync-cache
+ * source hashes, and the per-symbol `sourceHash` of the generated coordinate
+ * artifact. A file whose bytes match that evidence has not changed since it
+ * was compiled, however new its mtime (a fresh clone, a checkout, a touch).
+ */
+class CompiledContentEvidence {
+    workspaceRoot;
+    hashes;
+    coordinateHashes = null;
+    manifestState = new Map();
+    constructor(workspaceRoot, storePath) {
+        this.workspaceRoot = workspaceRoot;
+        const cache = record(readJson(path.join(storePath, "sync-cache.json")));
+        const hashes = record(cache?.hashes) ?? {};
+        this.hashes = Object.fromEntries(Object.entries(hashes).filter((entry) => typeof entry[1] === "string"));
+    }
+    fileHash(relative) {
+        try {
+            return sha256(readFileSync(path.resolve(this.workspaceRoot, relative)));
+        }
+        catch {
+            return null;
+        }
+    }
+    manifest(key) {
+        const cached = this.manifestState.get(key);
+        if (cached)
+            return cached;
+        const absolute = path.resolve(this.workspaceRoot, key);
+        let state = { matches: false, sources: new Set() };
+        try {
+            const matches = hashManifestWithCoordinates(this.workspaceRoot, absolute, path.join(path.dirname(absolute), "symbol-coordinates.yaml")) === this.hashes[key];
+            const parsed = record(parseYAML(readFileSync(absolute, "utf8")));
+            const sources = new Set();
+            for (const symbol of Array.isArray(parsed?.symbols)
+                ? parsed.symbols
+                : []) {
+                const row = record(symbol);
+                const source = row?.sourceFile ?? row?.source;
+                if (typeof source === "string" && source.length > 0)
+                    sources.add(source.replaceAll("\\", "/"));
+            }
+            state = { matches, sources };
+        }
+        catch {
+            // An unreadable manifest proves nothing; keep the reason.
+        }
+        this.manifestState.set(key, state);
+        return state;
+    }
+    coordinates() {
+        if (this.coordinateHashes)
+            return this.coordinateHashes;
+        const byFile = new Map();
+        for (const key of Object.keys(this.hashes)) {
+            if (!isSymbolsManifestPath(key) || !key.endsWith("symbols.yaml"))
+                continue;
+            const artifact = path.resolve(this.workspaceRoot, path.dirname(key), "symbol-coordinates.yaml");
+            if (!existsSync(artifact))
+                continue;
+            try {
+                const parsed = record(parseYAML(readFileSync(artifact, "utf8")));
+                for (const value of Object.values(record(parsed?.coordinates) ?? {})) {
+                    const row = record(value);
+                    if (typeof row?.sourceFile !== "string" ||
+                        typeof row.sourceHash !== "string")
+                        continue;
+                    const hashes = byFile.get(row.sourceFile) ?? new Set();
+                    hashes.add(row.sourceHash);
+                    byFile.set(row.sourceFile, hashes);
+                }
+            }
+            catch {
+                // A malformed artifact proves nothing.
+            }
+        }
+        this.coordinateHashes = byFile;
+        return byFile;
+    }
+    /** True only when recorded evidence proves the file's bytes are unchanged. */
+    unchanged(relative) {
+        const key = relative.replaceAll("\\", "/");
+        if (isSymbolsManifestPath(key) && this.hashes[key] !== undefined)
+            return this.manifest(key).matches;
+        const current = this.fileHash(key);
+        if (current === null)
+            return false;
+        const cached = this.hashes[key];
+        if (cached !== undefined)
+            return cached === current;
+        const coordinate = this.coordinates().get(key);
+        if (coordinate !== undefined && coordinate.size > 0)
+            return [...coordinate].every((hash) => hash === current);
+        // A code file that is only referenced from a symbol manifest is covered
+        // by that manifest's composite hash, which includes every referenced
+        // source's bytes.
+        return Object.keys(this.hashes).some((manifestKey) => {
+            if (!isSymbolsManifestPath(manifestKey))
+                return false;
+            const manifest = this.manifest(manifestKey);
+            return manifest.sources.has(key) && manifest.matches;
+        });
+    }
+}
+/**
+ * Drop mtime-only stale reasons whose file content provably matches what the
+ * store compiled. Reasons without such evidence are kept.
+ */
+// implements REQ-cli-status-pre-first-sync
+export function confirmSourceNewerReasons(workspaceRoot, storePath, reasons) {
+    const kept = [];
+    const dropped = [];
+    let evidence = null;
+    for (const reason of reasons) {
+        if (typeof reason.code !== "string" ||
+            !MTIME_SOURCE_REASON_CODES.has(reason.code) ||
+            typeof reason.path !== "string") {
+            kept.push(reason);
+            continue;
+        }
+        evidence ??= new CompiledContentEvidence(workspaceRoot, storePath);
+        if (evidence.unchanged(reason.path))
+            dropped.push(reason);
+        else
+            kept.push(reason);
+    }
+    return { kept, dropped };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.17.0",
+  "version": "2.18.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -235,7 +235,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.18.2",
+    "kibi-core": "^0.19.0",
     "kibi-plugin-builtin": "^0.5.0",
     "kibi-plugin-sdk": "^0.5.0",
     "kibi-swipl": "^1.0.1",

package/src/public/operations/contracts.ts

@@ -452,6 +452,8 @@ const BASE_DATA_SCHEMAS: Readonly<
       truncated: booleanValue,
       queryAnalysis: recordValue,
       answer: recordValue,
+      branch: { type: ["string", "null"] },
+      branchStore: recordValue,
     },
     ["results", "count"],
   ),
@@ -476,6 +478,7 @@ const BASE_DATA_SCHEMAS: Readonly<
     staleReasons: recordArray,
     staleReasonCount: integerValue,
     staleReasonsTruncated: booleanValue,
+    notices: recordArray,
     branchAttachment: recordValue,
     proofSnapshotChanges: recordArray,
     proofSnapshotChangeCount: integerValue,

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

@@ -21,8 +21,10 @@ import {
   branchStoreReason,
   inspectBranchStore,
   storeLockJournalReason,
+  storeLockTakeoverReason,
   uncompiledBranchStoreReason,
 } from "../../utils/branch-store.js";
+import { confirmSourceNewerReasons } from "../../utils/content-freshness.js";
 import {
   loadEntities,
   loadSearchCandidates,
@@ -78,8 +80,47 @@ export type SearchPayload = {
   readonly truncated?: boolean;
   readonly queryAnalysis?: IntentSearchAnalysis;
   readonly answer?: SearchAnswer;
+  /** The Kibi branch whose store was searched, when the runtime attached one. */
+  readonly branch?: string | null;
+  /** Present when the searched store was never compiled for this branch. */
+  readonly branchStore?: SearchBranchStoreNotice;
 };
 
+export type SearchBranchStoreNotice = {
+  readonly state: "not_compiled";
+  readonly code: typeof BRANCH_STORE_NOT_COMPILED;
+  readonly path: string;
+  readonly detail: string;
+  readonly remediation: Readonly<Record<string, unknown>>;
+};
+
+/**
+ * An empty result from a store that was never compiled says nothing about
+ * the authored requirements, so search reports the store state itself (the
+ * same reason kb_status and kb_check use) instead of a bare "no results".
+ */
+// implements REQ-cli-status-pre-first-sync, REQ-mcp-search-discovery
+function uncompiledSearchNotice(
+  context: OperationContext,
+): SearchBranchStoreNotice | null {
+  const attachment = context.branchAttachment;
+  if (attachment === undefined) return null;
+  const store = inspectBranchStore(context.workspaceRoot, attachment.kbBranch);
+  const reason = uncompiledBranchStoreReason(
+    context.workspaceRoot,
+    store,
+    attachment.kbBranch,
+  );
+  if (reason === null) return null;
+  return {
+    state: "not_compiled",
+    code: BRANCH_STORE_NOT_COMPILED,
+    path: store.path,
+    detail: String(reason.detail),
+    remediation: reason.remediation as Readonly<Record<string, unknown>>,
+  };
+}
+
 export type StatusInput = Readonly<Record<string, never>>;
 
 export type StatusPayload = {
@@ -99,6 +140,8 @@ export type StatusPayload = {
   readonly staleReasons?: readonly Record<string, unknown>[];
   readonly staleReasonCount?: number;
   readonly staleReasonsTruncated?: boolean;
+  /** Informational, non-blocking observations (never make the KB stale). */
+  readonly notices?: readonly Record<string, unknown>[];
   readonly branchAttachment?: {
     readonly gitBranch: string;
     readonly kbBranch: string;
@@ -275,6 +318,15 @@ export async function executeSearch(
   validateEntityType(type);
   try {
     const prolog = requireProlog(context);
+    const branch = context.branchAttachment?.kbBranch ?? null;
+    const storeNotice = uncompiledSearchNotice(context);
+    const branchFields = {
+      branch,
+      ...(storeNotice ? { branchStore: storeNotice } : {}),
+    };
+    const storeNote = storeNotice
+      ? ` Note: ${storeNotice.detail} Run kibi sync before relying on search results.`
+      : "";
     const intentMode =
       rankingMode === "intent-v1" ||
       semanticFacets !== undefined ||
@@ -305,7 +357,7 @@ 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.
-      const text =
+      const text = `${
         intentResult.matches.length === 0
           ? `No intent search results for '${trimmedQuery}' (abstained).`
           : `Found ${intentResult.matches.length} intent search results for '${trimmedQuery}'${intentResult.analysis.ambiguous ? " (top matches are close; confirm before relying on one)" : ""}. Top: ${paginated
@@ -313,7 +365,8 @@ 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"}` : ""}.`
+      }${storeNote}`;
       return {
         content: [{ type: "text", text }],
         structuredContent: {
@@ -322,6 +375,7 @@ export async function executeSearch(
           truncated: offset + paginated.length < intentResult.matches.length,
           queryAnalysis: intentResult.analysis,
           ...(answerLayer ? { answer: answerLayer } : {}),
+          ...branchFields,
         },
       };
     }
@@ -342,7 +396,7 @@ export async function executeSearch(
       context.workspaceRoot,
     );
     const paginated = paginateResults(matches, limit, offset);
-    const text =
+    const text = `${
       matches.length === 0
         ? `No search results for '${trimmedQuery}'.`
         : `Found ${matches.length} search results for '${trimmedQuery}'. Showing ${paginated.length} (offset ${offset}, limit ${limit}): ${paginated
@@ -350,13 +404,15 @@ export async function executeSearch(
               (match) =>
                 `${String(match.entity.id ?? "")} [${match.reasons.join(", ")}]`,
             )
-            .join(", ")}`;
+            .join(", ")}`
+    }${storeNote}`;
     return {
       content: [{ type: "text", text }],
       structuredContent: {
         results: await projectMatches(prolog, paginated, fields),
         count: matches.length,
         truncated: offset + paginated.length < matches.length,
+        ...branchFields,
       },
     };
   } catch (error) {
@@ -460,7 +516,25 @@ export async function executeStatus(
         await ownedEngine?.terminate();
       }
     const snapshotEvidence = await readWorkspaceSnapshot(context);
-    const existingReasons = payload.staleReasons ?? [];
+    // implements REQ-cli-status-pre-first-sync
+    // Prolog compares file times only. A fresh clone or a checkout rewrites
+    // every mtime without changing a byte, so confirm each "newer" source
+    // against the content hashes the last compilation recorded.
+    const prologReasons = payload.staleReasons ?? [];
+    const confirmed = confirmSourceNewerReasons(
+      context.workspaceRoot,
+      store.path,
+      prologReasons,
+    );
+    const existingReasons = confirmed.kept;
+    if (
+      confirmed.dropped.length > 0 &&
+      confirmed.kept.length === 0 &&
+      payload.staleReasonsTruncated !== true &&
+      payload.syncState === "stale"
+    ) {
+      payload = { ...payload, syncState: "fresh", dirty: false };
+    }
     // implements REQ-cli-status-pre-first-sync
     // A missing or empty store beside authored sources gets the one reason
     // whose remediation works (kibi sync); `kibi branch ensure` alone would
@@ -473,6 +547,9 @@ export async function executeStatus(
       ) ?? branchStoreReason(store);
     const storeUncompiled = storeReason?.code === BRANCH_STORE_NOT_COMPILED;
     const lockReason = storeLockJournalReason(store.path);
+    // implements REQ-core-journaled-engine-persistence
+    // A stale-lock takeover heals itself; report it without making the KB stale.
+    const takeoverNotice = storeLockTakeoverReason(store.path);
     const compilerReason = compilerFingerprintReason(store.path);
     const engineReason = engineStatus
       ? {
@@ -514,6 +591,7 @@ export async function executeStatus(
       ...(storeUncompiled ? { syncState: "stale", dirty: true } : {}),
       branchAttachment: attachment,
       branchStore: store,
+      ...(takeoverNotice ? { notices: [takeoverNotice] } : {}),
       ...(engineStatus ? { engineStatus } : {}),
       staleReasons,
       staleReasonCount: staleReasons.length,
@@ -661,7 +739,7 @@ export async function executeStatus(
       content: [
         {
           type: "text",
-          text: `Branch ${payload.branch} is ${enrichedPayload.syncState} (snapshot ${payload.snapshotId}, dirty=${enrichedPayload.dirty}, proofSnapshot=${enrichedPayload.proofSnapshot})${storeUncompiled ? `. Blocking: ${String(storeReason?.detail)} Run kibi sync.` : ""}`,
+          text: `Branch ${payload.branch} is ${enrichedPayload.syncState} (snapshot ${payload.snapshotId}, dirty=${enrichedPayload.dirty}, proofSnapshot=${enrichedPayload.proofSnapshot})${storeUncompiled ? `. Blocking: ${String(storeReason?.detail)} Run kibi sync.` : ""}${takeoverNotice ? `. Note: ${String(takeoverNotice.detail)}` : ""}`,
         },
       ],
       structuredContent: statusWithPlan,