kibi-cli 2.4.0 → 2.5.0

package/dist/extractors/markdown.d.ts

@@ -1,3 +1,4 @@
+import { type EntityOrigin } from "../public/entity-origin.js";
 import { type ProofBinding, type ProofContract } from "../public/proof-protocol.js";
 import { type ProofReceipt } from "../public/proof-receipt.js";
 export interface ExtractedEntity {
@@ -13,6 +14,7 @@ export interface ExtractedEntity {
     priority?: string;
     severity?: string;
     text_ref?: string;
+    origin?: EntityOrigin;
     semantic_text?: string;
     logic_claims?: string[];
     semantic_clauses?: string[];
@@ -30,6 +32,11 @@ export interface ExtractedEntity {
     verification_perspective?: "internal" | "consumer";
     proof_exempt?: boolean;
     proof_exempt_reason?: string;
+    approved_by?: string;
+    approval_ref?: string;
+    rationale?: string;
+    exempts_claims?: string[];
+    expects?: "success" | "rejection" | "error";
     proof_contract?: ProofContract;
     proof_bindings?: readonly ProofBinding[];
     proof_receipts?: readonly ProofReceipt[];
@@ -57,6 +64,7 @@ export interface ExtractedEntity {
     argument_names?: string[];
     argument_types?: string[];
     argument_descriptions?: string[];
+    key_arguments?: string[];
     aliases?: string[];
     examples?: string[];
     predicate_args?: string[];

package/dist/extractors/markdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/extractors/markdown.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/extractors/markdown.ts"],"names":[],"mappings":"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"}

package/dist/extractors/markdown.js

@@ -20,6 +20,7 @@ import { readFileSync } from "node:fs";
 import Ajv from "ajv";
 import { load as yamlLoad } from "js-yaml";
 import { semanticClaimKey } from "../operations/semantic-advisor/clauses.js";
+import { normalizeEntityOrigin, } from "../public/entity-origin.js";
 import { PROOF_BINDINGS_SCHEMA, PROOF_CONTRACT_SCHEMA, } from "../public/proof-protocol.js";
 import { proofReceiptHistoryErrors, } from "../public/proof-receipt.js";
 import entitySchema from "../schemas/entity.schema.json" with { type: "json" };
@@ -61,6 +62,7 @@ const FACT_STRING_ARRAY_FIELDS = [
     "argument_names",
     "argument_types",
     "argument_descriptions",
+    "key_arguments",
     "aliases",
     "examples",
     "predicate_args",
@@ -114,6 +116,8 @@ const VALID_RELATIONSHIP_TYPES = new Set([
     "consumes",
     "supersedes",
     "restates",
+    "assumes",
+    "exempts",
     "relates_to",
 ]);
 const VALID_RELATIONSHIP_DIRECTIONS = [
@@ -139,6 +143,8 @@ const VALID_RELATIONSHIP_DIRECTIONS = [
     { type: "supersedes", from: "adr", to: "adr" },
     { type: "supersedes", from: "req", to: "req" },
     { type: "restates", from: "req", to: "req" },
+    { type: "assumes", from: "scenario", to: "fact" },
+    { type: "exempts", from: "req", to: "req" },
 ];
 const RELATIONSHIP_TYPE_DISPLAY_LIST = Array.from(VALID_RELATIONSHIP_TYPES)
     .sort()
@@ -398,6 +404,17 @@ function extractFromMarkdownContent(content, filePath) {
         if (data.text_ref !== undefined) {
             entity.text_ref = data.text_ref;
         }
+        // implements REQ-004
+        if (data.origin !== undefined) {
+            const normalized = normalizeEntityOrigin(data.origin);
+            if ("error" in normalized) {
+                throw new FrontmatterError(`Invalid origin: ${normalized.error}`, filePath, {
+                    classification: "Invalid Entity Origin",
+                    hint: "Use origin: {kind: human|agent|migration|import, ref, approved_by, recorded_at}; only kind is required.",
+                });
+            }
+            entity.origin = normalized.origin;
+        }
         if (type === "req" && data.semantic_text !== undefined) {
             entity.semantic_text = data.semantic_text;
         }
@@ -421,6 +438,18 @@ function extractFromMarkdownContent(content, filePath) {
         if (type === "req" && data.semantic_source_hash !== undefined) {
             entity.semantic_source_hash = data.semantic_source_hash;
         }
+        // implements REQ-kibi-scenario-feasibility-v2
+        if (type === "scenario" && data.expects !== undefined) {
+            if (data.expects !== "success" &&
+                data.expects !== "rejection" &&
+                data.expects !== "error") {
+                throw new FrontmatterError("Invalid expects; expected success, rejection or error", filePath, {
+                    classification: "Invalid Scenario Outcome",
+                    hint: "Set expects: success, expects: rejection or expects: error on the scenario.",
+                });
+            }
+            entity.expects = data.expects;
+        }
         if (type === "req" && data.proof_exempt !== undefined) {
             if (typeof data.proof_exempt !== "boolean") {
                 throw new FrontmatterError("Invalid proof_exempt; expected true or false", filePath, {
@@ -440,6 +469,34 @@ function extractFromMarkdownContent(content, filePath) {
             }
             entity.proof_exempt_reason = data.proof_exempt_reason;
         }
+        // implements REQ-kibi-scenario-feasibility-v2
+        // Human approval of an exception requirement; only an approved exception
+        // makes a success scenario feasible.
+        for (const field of ["approved_by", "approval_ref"]) {
+            if (type !== "req" || data[field] === undefined)
+                continue;
+            if (typeof data[field] !== "string" || data[field].trim() === "") {
+                throw new FrontmatterError(`Invalid ${field}; expected a non-empty string`, filePath, {
+                    classification: "Invalid Exception Approval",
+                    hint: "Set approved_by to the approving person or role (and optionally approval_ref to the decision record) on the exception requirement.",
+                });
+            }
+            entity[field] = data[field];
+        }
+        // implements REQ-core-validation-rules
+        // Why the requirement exists; requirement-rationale-missing reads it.
+        if (type === "req" && data.rationale !== undefined) {
+            if (typeof data.rationale !== "string" || data.rationale.trim() === "") {
+                throw new FrontmatterError("Invalid rationale; expected a non-empty string", filePath, {
+                    classification: "Invalid Rationale",
+                    hint: "Set rationale to one or two sentences saying why the requirement exists, or remove the field.",
+                });
+            }
+            entity.rationale = data.rationale;
+        }
+        if (type === "req" && Array.isArray(data.exempts_claims)) {
+            entity.exempts_claims = data.exempts_claims.filter((value) => typeof value === "string");
+        }
         if (type !== "fact") {
             const invalidFactField = FACT_ONLY_FIELDS.find((field) => data[field] !== undefined);
             if (invalidFactField) {

package/dist/extractors/relationships.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../src/extractors/relationships.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,KAAK,kBAAkB,EAAa,MAAM,4BAA4B,CAAC;AAEhF,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE;QACT,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,qBAAqB,EAAE,CAAC;CACxC;AA0BD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,gBAAgB,EAAE,MAAM,GACvB,qBAAqB,EAAE,CAmBzB;AAED,gFAAgF;AAChF,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,GAChB,qBAAqB,CAiBvB;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,kBAAkB,GACzB,qBAAqB,GAAG,IAAI,CAyC9B;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,EAAE,GAC/B,qBAAqB,EAAE,CAEzB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,qBAAqB,EAAE,EACtC,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAC1B,KAAK,CAAC;IACP,YAAY,EAAE,qBAAqB,CAAC;IACpC,KAAK,EAAE,cAAc,GAAG,YAAY,CAAC;CACtC,CAAC,CAgBD"}
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../src/extractors/relationships.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,KAAK,kBAAkB,EAAa,MAAM,4BAA4B,CAAC;AAEhF,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE;QACT,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,qBAAqB,EAAE,CAAC;CACxC;AA4BD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,gBAAgB,EAAE,MAAM,GACvB,qBAAqB,EAAE,CAmBzB;AAED,gFAAgF;AAChF,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,GAChB,qBAAqB,CAiBvB;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,kBAAkB,GACzB,qBAAqB,GAAG,IAAI,CAyC9B;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,EAAE,GAC/B,qBAAqB,EAAE,CAEzB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,qBAAqB,EAAE,EACtC,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAC1B,KAAK,CAAC;IACP,YAAY,EAAE,qBAAqB,CAAC;IACpC,KAAK,EAAE,cAAc,GAAG,YAAY,CAAC;CACtC,CAAC,CAgBD"}

package/dist/extractors/relationships.js

@@ -39,6 +39,8 @@ const VALID_RELATIONSHIP_TYPES = new Set([
     "consumes",
     "supersedes",
     "restates",
+    "assumes",
+    "exempts",
     "relates_to",
 ]);
 /**

package/dist/intent-search.d.ts

@@ -43,6 +43,7 @@ export type IntentSearchAnalysis = Readonly<{
     topScore: number | null;
     topTwoMargin: number | null;
     abstained: boolean;
+    ambiguous: boolean;
 }>;
 export type IntentSearchResult = Readonly<{
     matches: readonly IntentSearchMatch[];
@@ -53,7 +54,9 @@ type GraphEdge = Readonly<{
     from: string;
     to: string;
 }>;
-export declare function rankIntentEntities(entities: readonly Record<string, unknown>[], options: IntentSearchOptions, workspaceRoot: string, graphEdges?: readonly GraphEdge[]): Promise<IntentSearchResult>;
+/** Markdown bodies already read in this search, keyed by entity source. */
+export type MarkdownBodyCache = Map<string, string | null>;
+export declare function rankIntentEntities(entities: readonly Record<string, unknown>[], options: IntentSearchOptions, workspaceRoot: string, graphEdges?: readonly GraphEdge[], bodyCache?: MarkdownBodyCache): Promise<IntentSearchResult>;
 export declare function graphGoal(seedIds: readonly string[], depth: 1 | 2): string;
 export declare function executeIntentSearch(options: IntentSearchOptions, prolog: PrologPort, workspaceRoot: string): Promise<IntentSearchResult>;
 export declare function validateIntentSearchInput(input: IntentSearchOptions): void;

package/dist/intent-search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"intent-search.d.ts","sourceRoot":"","sources":["../src/intent-search.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"intent-search.d.ts","sourceRoot":"","sources":["../src/intent-search.ts"],"names":[],"mappings":"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"}

package/dist/intent-search.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { escapeAtom, normalizeEntityId, parseTriples } from "./prolog/codec.js";
-import { SEARCH_CANDIDATE_PAGE_SIZE, listSearchCandidates, loadEntities, loadSearchCandidates, } from "./public/operations/discovery-entities.js";
+import { SEARCH_CANDIDATE_PAGE_SIZE, listSearchCandidates, loadEntities, loadEntityRows, loadSearchCandidates, } from "./public/operations/discovery-entities.js";
 import { loadMarkdownBody } from "./search-ranking.js";
 const GRAPH_RELATIONSHIPS = [
     "implements",
@@ -13,6 +13,7 @@ const GRAPH_RELATIONSHIPS = [
     "requires_property",
     "requires_predicate",
     "requires_rule",
+    "supersedes",
 ];
 const FACET_NAMES = [
     "actors",
@@ -21,23 +22,92 @@ const FACET_NAMES = [
     "constraints",
     "aliases",
 ];
+// Function words and question scaffolding carry no domain signal. Without
+// them, "how should kibi handle a detached HEAD?" scores on "detached" and
+// "head" rather than on how many entities mention "should". The frame of the
+// questions kb_search invites ("what governs X?", "what must stay true when
+// X?") is scaffolding too: entries are stemmed forms, so "govern" also drops
+// "governs", "governing" and "governed".
 const STOP_WORDS = new Set([
     "a",
+    "about",
     "an",
     "and",
+    "any",
     "are",
+    "as",
+    "at",
     "be",
     "by",
+    "can",
+    "could",
+    "did",
+    "do",
+    "does",
     "for",
+    "from",
+    "govern",
+    "happen",
+    "happens",
+    "how",
+    "i",
+    "if",
     "in",
+    "into",
     "is",
+    "it",
+    "its",
+    "me",
+    "must",
+    "my",
     "of",
     "on",
     "or",
+    "our",
+    "should",
+    "so",
+    "stay",
+    "tell",
+    "than",
+    "that",
     "the",
+    "their",
+    "them",
+    "then",
+    "there",
+    "these",
+    "they",
+    "this",
+    "those",
     "to",
+    "true",
+    "us",
+    "was",
+    "we",
+    "what",
+    "when",
+    "where",
+    "which",
+    "who",
+    "why",
+    "will",
     "with",
+    "would",
+    "you",
+    "your",
 ]);
+// Statuses whose entities no longer govern. They stay findable but rank
+// below current entities and are labelled in the match reasons.
+const NON_GOVERNING_STATUSES = new Set([
+    "superseded",
+    "deprecated",
+    "rejected",
+    "retired",
+    "obsolete",
+    "archived",
+]);
+const NON_GOVERNING_FACTOR = 0.5;
+const AMBIGUOUS_MARGIN = 0.05;
 const MAX_CANDIDATES = 10_000;
 const MAX_GRAPH_SEEDS = 5;
 const MAX_GRAPH_EDGES = 2_000;
@@ -52,8 +122,27 @@ function normalize(value) {
         .map((token) => token.length > 4 && token.endsWith("s") && !token.endsWith("ss")
         ? token.slice(0, -1)
         : token)
+        .map(stem)
         .join(" ");
 }
+// A deliberately small suffix stripper so a question's verb meets the
+// entity's noun ("contradict" / "contradiction" / "contradictory",
+// "detached" / "detach"). Short tokens are left alone.
+const STEM_SUFFIXES = ["ation", "ion", "ing", "ory", "ed"];
+function stem(token) {
+    if (token.length < 6 || /\d/.test(token))
+        return token;
+    let stemmed = token;
+    for (const suffix of STEM_SUFFIXES) {
+        if (stemmed.endsWith(suffix) && stemmed.length - suffix.length >= 4) {
+            stemmed = stemmed.slice(0, -suffix.length);
+            break;
+        }
+    }
+    return stemmed.length > 4 && stemmed.endsWith("e")
+        ? stemmed.slice(0, -1)
+        : stemmed;
+}
 function tokens(value) {
     return Array.from(new Set(normalize(value)
         .split(" ")
@@ -158,7 +247,16 @@ function facetValues(facets) {
     }
     return result;
 }
-function scoreEntity(entity, queryTokens, facets, sourceEvidence, graphEvidence, documentFrequency, documentCount, body) {
+// Both ranking passes of a search score the same candidate objects, and
+// tokenizing them is most of the ranking cost on a large KB, so each entity is
+// tokenized once. Keyed weakly by the entity object, so nothing outlives the
+// search that loaded it.
+const ENTITY_TOKENS = new WeakMap();
+// implements REQ-kibi-intent-aware-source-discovery
+function entityTokens(entity, body) {
+    const cached = ENTITY_TOKENS.get(entity);
+    if (cached !== undefined && cached.body === body)
+        return cached;
     const title = normalize(String(entity.title ?? ""));
     const metadata = normalize([
         entity.id,
@@ -171,25 +269,47 @@ function scoreEntity(entity, queryTokens, facets, sourceEvidence, graphEvidence,
     ]
         .filter((value) => typeof value === "string")
         .join(" "));
-    const bodyText = normalize(body ?? "");
-    const titleTokens = new Set(tokens(title));
-    const metadataTokens = new Set(tokens(metadata));
-    const bodyTokens = new Set(tokens(bodyText));
+    const computed = {
+        body,
+        title: new Set(tokens(title)),
+        metadata: new Set(tokens(metadata)),
+        bodyTokens: new Set(tokens(normalize(body ?? ""))),
+        document: tokens(`${entityText(entity)} ${body ?? ""}`),
+    };
+    ENTITY_TOKENS.set(entity, computed);
+    return computed;
+}
+function scoreEntity(entity, queryTokens, facets, sourceEvidence, graphEvidence, documentFrequency, documentCount, body, superseded = false) {
+    const { title: titleTokens, metadata: metadataTokens, bodyTokens, } = entityTokens(entity, body);
     const allSignalTokens = Array.from(new Set(queryTokens));
-    const lexical = allSignalTokens.reduce((sum, token) => {
+    // BM25-style inverse document frequency over title, metadata and body:
+    // a token most entities contain (a project name, "requirement") adds
+    // almost nothing, and the score is the share of the query's total
+    // discriminating weight this entity matches.
+    // Half of the lexical score is where the matched weight sits (title over
+    // metadata over body); the other half is how much of the query's
+    // discriminating weight the entity covers at all, so an entity matching
+    // the rare terms in its body outranks one matching a common term in its
+    // title.
+    let placed = 0;
+    let covered = 0;
+    let total = 0;
+    for (const token of allSignalTokens) {
         const frequency = documentFrequency.get(token) ?? 0;
-        const idf = Math.log(1 + (documentCount + 1) / (frequency + 1));
+        const idf = Math.log(1 + (documentCount - frequency + 0.5) / (frequency + 0.5));
         const fieldWeight = titleTokens.has(token)
-            ? 3
+            ? 1
             : metadataTokens.has(token)
-                ? 1.5
+                ? 0.65
                 : bodyTokens.has(token)
-                    ? 0.75
+                    ? 0.5
                     : 0;
-        return sum + idf * fieldWeight;
-    }, 0);
-    const lexicalMax = Math.max(1, allSignalTokens.length * 4);
-    const lexicalScore = Math.min(1, lexical / lexicalMax);
+        placed += idf * fieldWeight;
+        if (fieldWeight > 0)
+            covered += idf;
+        total += idf;
+    }
+    const lexicalScore = total > 0 ? Math.min(1, (placed / total + covered / total) / 2) : 0;
     const matchedFacets = [];
     let facetScore = 0;
     for (const facet of facets) {
@@ -207,11 +327,17 @@ function scoreEntity(entity, queryTokens, facets, sourceEvidence, graphEvidence,
     facetScore = Math.min(1, facetScore / Math.max(1, facets.length));
     const sourceScore = sourceEvidence.length > 0 ? 1 : 0;
     const graphScore = graphEvidence.length > 0 ? Math.min(1, graphEvidence.length / 2) : 0;
+    const status = String(entity.status ?? "")
+        .trim()
+        .toLowerCase();
+    const nonGoverning = NON_GOVERNING_STATUSES.has(status) || superseded;
     const score = Math.min(1, lexicalScore * 0.58 +
         facetScore * 0.17 +
         sourceScore * 0.2 +
-        graphScore * 0.05);
+        graphScore * 0.05) * (nonGoverning ? NON_GOVERNING_FACTOR : 1);
     const reasons = [];
+    if (nonGoverning)
+        reasons.push(superseded ? "demoted: superseded" : `demoted: ${status}`);
     if (lexicalScore > 0)
         reasons.push("intent token match");
     if (matchedFacets.length > 0)
@@ -227,24 +353,45 @@ function scoreEntity(entity, queryTokens, facets, sourceEvidence, graphEvidence,
     }
     return { score, reasons, matchedFacets };
 }
-function buildDocumentFrequency(entities) {
+function buildDocumentFrequency(entities, bodies) {
     const frequency = new Map();
     for (const entity of entities) {
-        const seen = new Set(tokens(entityText(entity)));
+        const seen = entityTokens(entity, bodies.get(entity) ?? null).document;
         for (const token of seen)
             frequency.set(token, (frequency.get(token) ?? 0) + 1);
     }
     return frequency;
 }
+/** Files read at once, well under common open-file limits. */
+const BODY_READ_CONCURRENCY = 32;
+// implements REQ-kibi-intent-aware-source-discovery
+async function readBodies(entities, workspaceRoot, cache) {
+    const missing = [
+        ...new Set(entities.map((entity) => String(entity.source ?? ""))),
+    ].filter((source) => !cache.has(source));
+    for (let start = 0; start < missing.length; start += BODY_READ_CONCURRENCY) {
+        const batch = missing.slice(start, start + BODY_READ_CONCURRENCY);
+        const loaded = await Promise.all(batch.map((source) => loadMarkdownBody(source, workspaceRoot)));
+        batch.forEach((source, index) => cache.set(source, loaded[index] ?? null));
+    }
+    return new Map(entities.map((entity) => [
+        entity,
+        cache.get(String(entity.source ?? "")) ?? null,
+    ]));
+}
 // implements REQ-kibi-intent-aware-source-discovery
-export async function rankIntentEntities(entities, options, workspaceRoot, graphEdges = []) {
+export async function rankIntentEntities(entities, options, workspaceRoot, graphEdges = [], bodyCache = new Map()) {
     const queryTokens = tokens(options.query);
     const facets = facetValues(options.semanticFacets);
     const allTokens = Array.from(new Set([
         ...queryTokens,
         ...facets.flatMap((facet) => tokens(facet.value)),
     ]));
-    const documentFrequency = buildDocumentFrequency(entities);
+    const bodies = await readBodies(entities, workspaceRoot, bodyCache);
+    const documentFrequency = buildDocumentFrequency(entities, bodies);
+    const supersededIds = new Set(graphEdges
+        .filter((edge) => edge.relationship === "supersedes")
+        .map((edge) => edge.to));
     const ranked = [];
     const minScore = options.minScore ?? 0.18;
     const graphByEntity = new Map();
@@ -267,8 +414,8 @@ export async function rankIntentEntities(entities, options, workspaceRoot, graph
         // Keep evidence useful for agents and bounded for transport. The score is
         // already capped; unbounded parallel paths only add noise to receipts.
         const graphEvidence = (graphByEntity.get(entityId) ?? []).slice(0, 8);
-        const body = await loadMarkdownBody(String(entity.source ?? ""), workspaceRoot);
-        const scored = scoreEntity(entity, allTokens, facets, sourceEvidence, graphEvidence, documentFrequency, entities.length, body);
+        const body = bodies.get(entity) ?? null;
+        const scored = scoreEntity(entity, allTokens, facets, sourceEvidence, graphEvidence, documentFrequency, entities.length, body, supersededIds.has(entityId));
         if (scored.score < minScore)
             continue;
         const snippet = body
@@ -285,7 +432,9 @@ export async function rankIntentEntities(entities, options, workspaceRoot, graph
                 matchedFacets: scored.matchedFacets,
                 sourceMatches: sourceEvidence,
                 graphPaths: graphEvidence,
-                abstentionEligible: scored.score < minScore,
+                // Accepted, but within 0.05 of the threshold: a weak match the
+                // caller should confirm before relying on it.
+                abstentionEligible: scored.score < minScore + AMBIGUOUS_MARGIN,
             },
         });
     }
@@ -312,6 +461,8 @@ export async function rankIntentEntities(entities, options, workspaceRoot, graph
             topScore,
             topTwoMargin,
             abstained: ranked.length === 0,
+            // Two leading matches this close are not a confident single answer.
+            ambiguous: topTwoMargin !== null && topTwoMargin < AMBIGUOUS_MARGIN,
         },
     };
 }
@@ -421,7 +572,9 @@ async function loadIntentCandidates(prolog, options) {
 // implements REQ-kibi-intent-aware-source-discovery
 export async function executeIntentSearch(options, prolog, workspaceRoot) {
     const candidates = await loadIntentCandidates(prolog, options);
-    const firstPass = await rankIntentEntities(candidates, options, workspaceRoot);
+    // Both ranking passes read the same Markdown bodies; read each file once.
+    const bodies = new Map();
+    const firstPass = await rankIntentEntities(candidates, options, workspaceRoot, [], bodies);
     const sourceSeeds = firstPass.matches
         .filter((match) => match.evidence.sourceMatches.length > 0)
         .map((match) => String(match.entity.id ?? ""));
@@ -435,17 +588,17 @@ export async function executeIntentSearch(options, prolog, workspaceRoot) {
     const graphEdges = await queryGraphEdges(prolog, seeds);
     const knownIds = new Set(candidates.map((entity) => `${String(entity.type ?? "")}::${String(entity.id ?? "")}`));
     const relatedIds = Array.from(new Set(graphEdges.flatMap((edge) => [edge.from, edge.to]))).filter((id) => !seeds.includes(id));
-    for (const id of relatedIds.slice(0, MAX_GRAPH_SEEDS * 4)) {
-        const related = await loadEntities(prolog, { id });
-        for (const entity of related) {
-            const key = `${String(entity.type ?? "")}::${String(entity.id ?? "")}`;
-            if (!knownIds.has(key)) {
-                knownIds.add(key);
-                candidates.push(entity);
-            }
+    // One batched query of projected rows for the graph neighbours, rather
+    // than one engine round trip per neighbour.
+    const related = await loadEntityRows(prolog, relatedIds.slice(0, MAX_GRAPH_SEEDS * 4));
+    for (const entity of related) {
+        const key = `${String(entity.type ?? "")}::${String(entity.id ?? "")}`;
+        if (!knownIds.has(key)) {
+            knownIds.add(key);
+            candidates.push(entity);
         }
     }
-    return rankIntentEntities(candidates, options, workspaceRoot, graphEdges);
+    return rankIntentEntities(candidates, options, workspaceRoot, graphEdges, bodies);
 }
 // implements REQ-kibi-intent-aware-source-discovery
 export function validateIntentSearchInput(input) {

package/dist/operations/bootstrap/candidate-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"candidate-helpers.d.ts","sourceRoot":"","sources":["../../../src/operations/bootstrap/candidate-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,MAAM,CAMtD;AAED,wBAAgB,MAAM,CACpB,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,CAAA;CAAE,EAE5D,MAAM,EAAE,CAAC,EACT,aAAa,GAAE,SAAS;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB,EAAO,GACP,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAQnC;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,cAAc,GACvB,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAmC9C"}
+{"version":3,"file":"candidate-helpers.d.ts","sourceRoot":"","sources":["../../../src/operations/bootstrap/candidate-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAIrE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,MAAM,CAMtD;AAED,wBAAgB,MAAM,CACpB,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,CAAA;CAAE,EAE5D,MAAM,EAAE,CAAC,EACT,aAAa,GAAE,SAAS;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB,EAAO,GACP,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAQnC;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,cAAc,GACvB,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CA0C9C"}

package/dist/operations/bootstrap/candidate-helpers.js

@@ -1,3 +1,5 @@
+import { annotateModelRequirementStep } from "../modeling/model-requirement.js";
+import { semanticClaimKey } from "../semantic-advisor/clauses.js";
 export function confidenceBand(value) {
     return value >= 0.9 ? "high" : value >= 0.8 ? "medium" : "low";
 }
@@ -28,6 +30,7 @@ export function strictPlan(writeSet) {
             },
         ];
     }
+    const claimKey = semanticClaimKey(writeSet.req.properties.title);
     return [
         {
             type: "fact",
@@ -51,5 +54,9 @@ export function strictPlan(writeSet) {
                 to,
             })),
         },
-    ];
+    ].map((step) => annotateModelRequirementStep(step, {
+        claimKey,
+        statement: writeSet.req.properties.title,
+        logicClaims: [claimKey],
+    }));
 }

package/dist/operations/bootstrap/candidates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"candidates.d.ts","sourceRoot":"","sources":["../../../src/operations/bootstrap/candidates.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EACV,iBAAiB,EAGlB,MAAM,YAAY,CAAC;AAmHpB,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EAChC,aAAa,EAAE,MAAM,EACrB,sBAAsB,EAAE,OAAO,GAC9B,oBAAoB,CAsCtB"}
+{"version":3,"file":"candidates.d.ts","sourceRoot":"","sources":["../../../src/operations/bootstrap/candidates.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EACV,iBAAiB,EAGlB,MAAM,YAAY,CAAC;AA+GpB,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EAChC,aAAa,EAAE,MAAM,EACrB,sBAAsB,EAAE,OAAO,GAC9B,oBAAoB,CA4DtB"}