kibi-cli 2.36.0 → 2.39.0

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.32.0
+version: 2.37.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -137,7 +137,9 @@ For an edit that keeps the governing rule, limit the consultation before the edi
    `unknown`, or `none`, which is not proof), the `exceptions` that exempt it,
    and the `unknowns` the checks could not decide. Those links and verdicts are
    discovery, not proof. Pass `sourceLocations` before changing a source file,
-   and `rankingMode: "legacy"` for literal identifier lookups. See
+   and `rankingMode: "legacy"` for literal identifier lookups. A weak answer
+   may add `queryAnalysis.hints` (requirements the question may mean): re-ask
+   in their words, never cite a hint as the rule. See
    `resources/workflows.md` for the mode recipe.
 2. Resolve genuine ambiguity with the human; use `kb_model` for deterministic
    interpretation and typed facts.
@@ -286,7 +288,9 @@ authored. Each one is the order the write path accepts.
    its scenario: `specified_by` (req → scenario) is sent in the
    requirement's write, never in the scenario's, so create the scenario
    first, with `assumes` links (scenario → `property_value` fact, sent in
-   the scenario's own write) to the values its outcome relies on. Set
+   the scenario's own write) to the values its outcome relies on; add a
+   rejection scenario that assumes a forbidden value next to the success
+   one (see Quantified claims below). Set
    `expects` only on a scenario that has `assumes` links; `expects: success`
    without them only yields `scenario-feasibility-unknown` ("assumes
    nothing"). A
@@ -368,6 +372,14 @@ human sets `approved_by`; `kb_check` flags approvals an agent recorded without
 corroboration. Never fill in an approval yourself. Record why a requirement
 exists in `rationale`, or link the ADR that explains it.
 
+A signoff belongs to the change it approves. Ask for it before you open or
+merge the pull request, and when the person answers, record their answer
+(`approved_by` or a `*_waiver_approved_by` field set to them, their words in
+`origin.ref` or `approval_ref`) on the same branch and push it to the same pull
+request. Writing down an answer the person gave is not approving it yourself.
+Never open a separate pull request only to carry a signoff, firmness or waiver
+approval.
+
 ## Decision firmness
 
 Requirements and ADRs carry `firmness`, which says what you may do with them.
@@ -442,6 +454,41 @@ predicate bound with `harness_for` (scope `harness`) also counts toward
 `proved`; an intent-scope binding stays `tested`. When the `evidence-floor` rule fails, follow Debugging
 proof regressions in `resources/proof.md` and use `kibi proof explain`.
 
+## Quantified claims: model the dimension
+
+When a claim says every, each, all, any, only, at least, at most, exactly, a
+role, a status or a count, ground it on what varies, never on `= true`: an int
+count or bound (`role_count eq 1`, `uninstrumented_loaded_files eq 0`), a set,
+or a typed rule with a `forall` variable. Keep `value_type: bool` for genuinely
+binary properties (a flag is on). A `shadow_analysis` cue from `kb_model`
+(`mode: "analyze"`) with `kind: quantifier` or `numeric` and `represented:
+false` means the planned grounding hides the dimension. When
+`mode: "predicates"` finds no schema for such a claim, do not stop at the
+ontology-gap observation: call `kb_model` with `mode: "requirement"` and an
+int `subjectKey`/`propertyKey`/`operator`/`value` for the count, and keep the
+gap only when no count, set or rule expresses the claim.
+
+Specify the requirement with scenarios that carry their inputs. Each scenario
+sets `expects` and `assumes` its own `property_value` fact: same `subject_key`
+and `property_key` as the grounding, with the scenario's value. These
+assumed-value facts are linked only by the scenario's `assumes`, never by the
+requirement, so a forbidden value does not contradict the grounding; it is
+what makes the scenario a rejection. Write at least:
+
+- a success scenario assuming an allowed value (`expects: success`);
+- a rejection scenario assuming a forbidden value (`expects: rejection`, or
+  `error`); a scenario that only describes the refusal in prose, without
+  `expects` and `assumes`, does not count;
+- for a quantified claim, cases at zero, one and many when they differ.
+
+```json
+{"type":"fact","id":"FACT-member-role-count-2","properties":{"title":"Member holds two roles","status":"active","fact_kind":"property_value","subject_key":"organization.member","property_key":"role_count","operator":"eq","value_type":"int","value_int":2}}
+{"type":"scenario","id":"SCEN-member-two-roles-rejected","properties":{"title":"A member with two roles is rejected","status":"active","expects":"rejection"},"relationships":[{"type":"assumes","from":"SCEN-member-two-roles-rejected","to":"FACT-member-role-count-2"}]}
+```
+
+Then send `specified_by` to every scenario in the requirement's write.
+Details: `resources/fact-lanes.md`, Model the Dimension, Not the Verdict.
+
 ## Predicate Ontology Decision Tree
 
 Call `kb_model` with `mode: "analyze"` on the complete prose before encoding a clause.

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

@@ -15,6 +15,40 @@ Use the advisor-returned atomic inventory as the identity boundary. Trailing pun
 
 Example compound prose: “Checkout requires payment authorization before order submission, and customer data must be retained for 7 years.” This is two claims, not one. The first becomes `dependency_rule(checkout,payment_authorization,order_submission)`; the second becomes a strict retention property. Both fact records carry different advisor-issued claim keys, and both keys appear in the requirement manifest. A single `requires_predicate` edge is incomplete.
 
+## Model the Dimension, Not the Verdict
+
+A claim that says every, each, all, any, only, at least, at most, exactly, no more than, a role, a status or a count ranges over something. Ground it on the thing that varies, not on a boolean that says the claim holds:
+
+| The claim varies over | Ground it on |
+| --- | --- |
+| a count or bound ("at most 5 owners", "exactly one role") | `property_value` with `value_type: int` and `eq`/`lte`/`gte` |
+| each member of a collection ("every loaded file") | an int count of the members that break the rule (`eq 0`), or a typed rule with a `forall` variable over the member |
+| a closed set of values ("only admins and owners") | a canonical string set, or a predicate argument with `argument_constants` |
+| a status or lifecycle ("a closed invoice cannot reopen") | a typed rule over the status, or a `state_machine` proof |
+
+Use `value_type: bool` (`= true`) only when the property itself is binary: a flag is on, a feature is enabled. `module.loader.instruments_all_loaded_files = true` restates the claim and gives Kibi nothing that can vary: no boundary, no zero/one/many case, and no contradiction with another requirement that bounds the same count.
+
+`kb_model` (`mode: "analyze"`) lists `shadow_analysis` cues. A `quantifier` or `numeric` cue with `represented: false` means the grounding does not carry the dimension yet. Do not ignore it: re-plan the grounding as a count, a rule variable or a set before writing. When no typed shape fits, keep the clause `ontology_gap` rather than downgrading it to a boolean verdict.
+
+Example: "Each organization member must hold exactly one role."
+
+```yaml
+# Avoid: the verdict
+- { fact_kind: property_value, subject_key: organization.member, property_key: holds_exactly_one_role, operator: eq, value_type: bool, value_bool: true }
+# Prefer: the dimension
+- { fact_kind: property_value, subject_key: organization.member, property_key: role_count, operator: eq, value_type: int, value_int: 1 }
+```
+
+### Scenarios carry their inputs
+
+A requirement grounded on a dimension is specified by scenarios that pick values of it. Each scenario `assumes` the `property_value` facts that state its input (same `subject_key` and `property_key` as the requirement's grounding, with the scenario's value) and sets `expects`:
+
+- one success scenario whose assumed value the requirement allows (`role_count = 1`, `expects: success`);
+- at least one rejection or error scenario whose assumed value the requirement forbids (`role_count = 2`, `expects: rejection`): a requirement that constrains behavior is not specified by its happy path alone;
+- for a quantified claim, scenarios at zero, one and many of the varying thing whenever those behave differently (no files loaded, one file, several files).
+
+Assumed-value facts are ordinary `property_value` facts linked only by the scenario's `assumes`; never link them from the requirement. Only requirement-linked facts are compared for contradictions, so an assumed forbidden value (`role_count = 2` next to the grounding `role_count eq 1`) is not a conflict: it is the input that makes the scenario a rejection. A refusal described only in prose, without `expects` and `assumes`, does not specify anything Kibi can check. Create them and the scenarios before the requirement write that sends `specified_by`. `scenario-feasibility` then checks every success scenario against the requirement, and the `happy_path_only` proof gap reports a requirement none of whose scenarios expects rejection or error while assuming a value that opposes one of its claims.
+
 ## Predicate Lane (Relational Claims)
 
 Call `kb_model` with `mode: "analyze"`, then with `mode: "predicates"`. Apply a candidate only when its schema meaning and ordered arguments fit the claim. Use the returned `applyPlan` rather than hand-writing unsupported predicate names, and link the requirement to the predicate fact with `requires_predicate`.

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

@@ -173,7 +173,10 @@ left:
   Enum values, dict keys, list/tuple/set items) and rejects a
   certificate that does not cover exactly its members, so a hand-listed or
   partial domain stays `tested`. An import from build output is mapped back
-  to its source through `tsconfig.json` `outDir`/`rootDir`.
+  to its source through `tsconfig.json` `outDir`/`rootDir`. For a list of
+  records (a catalog), add `field: <name>` and pass
+  `key: (item) => item.<name>` to `exhaustiveCertificate`; the members are
+  that field's values.
 - `typecheck`: a witness file that stops compiling when a domain member
   goes unhandled (a switch ending in a `never` assignment, or a
   `satisfies Record<Domain, ...>` map). Set `witness.path` and
@@ -195,7 +198,8 @@ left:
   evaluates the number export itself and adds `variable eq value` as an
   assumption. For a count claim over a collection ("exactly 32 tools") add
   `measure: count` and name the list, set, map or object export; Kibi uses
-  its size, so do not add a number export just for the proof. A count
+  its size, so do not add a number export just for the proof. A dotted
+  export (`POLICY.eventLimit`) reads one field of an object export. A count
   claim needs only `value_source`. Naming the claim's own fact in
   `constraint_source` assumes the claim: without `value_source` Kibi counts
   that derivation as intent only (tested), and with it a code value that
@@ -244,7 +248,7 @@ left:
   `subset_of` and `excludes`. Rules over a machine use `transition`,
   `reachable`, `initial`, `terminal`, `state`.
 - `regex`: set `pattern_source` to a `RegExp`, a Python `re.compile(...)` or
-  a string constant. Model "X must match `re`" as a string fact with
+  a string constant (`export: BRAND.name` reads one field of an object). Model "X must match `re`" as a string fact with
   `operator: matches` (a JavaScript pattern with the `u` flag, matched
   whole); Kibi decides exact language equality and reports the shortest
   string only one side accepts. Backreferences, lookaround, `\b`, the `g`,
@@ -254,7 +258,8 @@ left:
 - `source`: Kibi reads a project source itself and checks a set fact
   against what it read, so the test only runs the proof (it may write
   nothing, or `sourceCertificate({ testId })`). Set `source: {reader, ...}`:
-  `json`/`yaml` (`file`, `path`, `select`), `glob` (`pattern`, `capture`),
+  `json`/`yaml` (`file`, `path`, `select`, `field` to read one key of
+  each list item, such as the `run` of each workflow step), `glob` (`pattern`, `capture`),
   `openapi` (`file`, `select: operations|unsecured_operations|...`),
   `references` (`files`, `extract: env|imports|calls|string_args|thrown|
   property`), `schema` (`format: drizzle|prisma|sql`, `select:
@@ -271,7 +276,10 @@ left:
   `nullable_fields` (only `eq`/`includes`) with bare members `name` for
   "every table" (it also covers tables added later) or `table.name` for
   one; `middleware` with `includes` for "every route under /p must use M"
-  (Kibi checks each route). Name middleware with `names_from`: a
+  (Kibi checks each route); `precedes` with `includes` and members
+  `"A -> B"` for an order in a list ("the gate runs before the push"):
+  A and B are both in the list and every A comes before every B. Name
+  middleware with `names_from`: a
   zero-argument factory export such as `requireAuth()` names the
   middleware it returns `requireAuth`. Write the fact with `kb_model`
   (requirement mode, `operator` plus a list `value`) or `kb_upsert`. The

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

@@ -78,6 +78,16 @@ no-answer, so widen the query or drop to lexical search rather than treating it
 as "nothing exists". A literal identifier lookup is still best served
 lexically.
 
+When the project activates a `kibi.search-hints.v1` plugin (for example
+`kibi-plugin-search-hints`), a weak or abstained intent answer also carries
+`queryAnalysis.hints`: up to ten current requirements the question may mean,
+found by meaning rather than shared words, each with a `score` and, when it
+was reached through a scenario, test or fact, that entity as `via`. Hints are
+suggestions, never governing requirements, and they never change the results
+or the answer layer. Re-ask `kb_search` in the words of a hint that fits, or
+pass them as `semanticFacets.aliases`, then read the requirement with
+`kb_query`; never cite a hint as the rule. `hints: false` turns them off.
+
 On the first page, intent mode also returns an answer layer in `data.answer`
 (`kibi.search-answer.v1`; turn it off with `answer: false`):
 

package/dist/relationships/shards.d.ts

@@ -30,6 +30,8 @@ export declare function computeShardPath(kbRoot: string, entityId: string): stri
  * Throws on parse errors.
  */
 export declare function readShard(shardPath: string): RelationshipRecord[];
+/** How many parsed shards the reuse memo holds; for tests of its bound. */
+export declare function parsedShardMemoSize(): number;
 /**
  * Parses relationship shard text read from `shardPath`.
  * Returns an empty array for blank text. Throws on parse errors.

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

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

package/dist/relationships/shards.js

@@ -51,7 +51,31 @@ export function readShard(shardPath) {
     if (!fs.existsSync(shardPath)) {
         return [];
     }
-    return parseShardText(fs.readFileSync(shardPath, "utf8"), shardPath);
+    const content = fs.readFileSync(shardPath, "utf8");
+    const parsed = parsedShards.get(content);
+    // rationale: parsing is a pure function of the text and callers get copies
+    // either way, so skipping the memo changes only the time a read takes.
+    // Stryker disable next-line ConditionalExpression
+    if (parsed !== undefined)
+        return parsed.map((record) => ({ ...record }));
+    const records = parseShardText(content, shardPath);
+    if (parsedShards.size >= PARSED_SHARD_LIMIT)
+        parsedShards.clear();
+    parsedShards.set(content, records.map((record) => ({ ...record })));
+    return records;
+}
+/**
+ * Parsed shards by their text. One check reads every shard for several rules
+ * (relationship parity, entity context); a shard's records are a pure
+ * function of its text, so an unchanged shard is parsed once per process.
+ * Callers get their own record copies.
+ */
+const PARSED_SHARD_LIMIT = 1024;
+const parsedShards = new Map();
+/** How many parsed shards the reuse memo holds; for tests of its bound. */
+// implements REQ-005
+export function parsedShardMemoSize() {
+    return parsedShards.size;
 }
 /**
  * Parses relationship shard text read from `shardPath`.

package/dist/schemas/entity.schema.json

@@ -562,6 +562,18 @@
             "minLength": 1,
             "description": "Requirement-only. Optional reference to the approval decision record (ticket, ADR or review link) for an exception requirement."
         },
+        "failure_side_waiver": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S",
+            "description": "Requirement-only. Why the requirement has no failure side to test: its claims state a capability or an output shape, so there is no input or attempt for Kibi to refuse. Waives the happy_path_only gap once failure_side_waiver_approved_by is set."
+        },
+        "failure_side_waiver_approved_by": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S",
+            "description": "Requirement-only. The person who accepted failure_side_waiver. Without it the waiver is reported as awaiting approval and the gap stays open."
+        },
         "rationale": {
             "type": "string",
             "minLength": 1,
@@ -684,6 +696,32 @@
                     },
                     "reason": {
                         "type": "string"
+                    },
+                    "dimension": {
+                        "type": "object",
+                        "required": [
+                            "quantifier",
+                            "rewrites"
+                        ],
+                        "properties": {
+                            "quantifier": {
+                                "type": "string",
+                                "minLength": 1
+                            },
+                            "rewrites": {
+                                "type": "array",
+                                "items": {
+                                    "type": "string",
+                                    "enum": [
+                                        "bound",
+                                        "rule",
+                                        "count",
+                                        "set"
+                                    ]
+                                }
+                            }
+                        },
+                        "additionalProperties": false
                     }
                 },
                 "additionalProperties": false
@@ -831,6 +869,11 @@
                             "type": "string",
                             "minLength": 1,
                             "description": "The name the domain is exported under in the symbol's source file, when the symbol's title is not that name."
+                        },
+                        "field": {
+                            "type": "string",
+                            "minLength": 1,
+                            "description": "exhaustive: when the export is a list of records, the field of each record that names a domain member (a catalog's name)."
                         }
                     },
                     "additionalProperties": false
@@ -861,7 +904,7 @@
                 },
                 "value_source": {
                     "type": "array",
-                    "description": "arithmetic and smt: code constants the assumptions read. Kibi evaluates each export at ingest and requires the certificate to assume the variable equals that value, so the proof is about the code and not only the knowledge base. With measure count the value is the size of a list, set, map or object export, so a count claim reads the collection itself. An entry {source, measure: count} counts the members Kibi reads from a project source (routes, tables, environment variables).",
+                    "description": "arithmetic and smt: code constants the assumptions read. Kibi evaluates each export at ingest and requires the certificate to assume the variable equals that value, so the proof is about the code and not only the knowledge base. With measure count the value is the size of a list, set, map or object export, so a count claim reads the collection itself. A dotted export (POLICY.eventLimit) reads one field of an object export. An entry {source, measure: count} counts the members Kibi reads from a project source (routes, tables, environment variables).",
                     "minItems": 1,
                     "items": {
                         "type": "object",
@@ -1597,6 +1640,30 @@
         "claim_text": {
             "type": "string"
         },
+        "dimension_waiver": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S",
+            "description": "Fact-only. Why the quantifier word in claim_text (each, every, all, or a cardinality bound) ranges over nothing, so the claim needs no count, set or rule. Waives dimension_unrepresented for the claim once dimension_waiver_approved_by is set."
+        },
+        "dimension_waiver_approved_by": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S",
+            "description": "Fact-only. The person who accepted dimension_waiver. Without it the waiver is reported as awaiting approval and the gap stays open."
+        },
+        "case_waiver": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S",
+            "description": "Fact-only. Why the edge cases Kibi derives from this fact (the value past a bound, a value outside a set) are covered some other way or cannot occur. Waives uncovered_case for the fact once case_waiver_approved_by is set."
+        },
+        "case_waiver_approved_by": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S",
+            "description": "Fact-only. The person who accepted case_waiver. Without it the waiver is reported as awaiting approval and the gap stays open."
+        },
         "predicate_name": {
             "type": "string"
         },
@@ -1834,6 +1901,26 @@
                                 "claim_text"
                             ]
                         },
+                        {
+                            "required": [
+                                "dimension_waiver"
+                            ]
+                        },
+                        {
+                            "required": [
+                                "dimension_waiver_approved_by"
+                            ]
+                        },
+                        {
+                            "required": [
+                                "case_waiver"
+                            ]
+                        },
+                        {
+                            "required": [
+                                "case_waiver_approved_by"
+                            ]
+                        },
                         {
                             "required": [
                                 "predicate_name"
@@ -2046,6 +2133,16 @@
                                 "approval_ref"
                             ]
                         },
+                        {
+                            "required": [
+                                "failure_side_waiver"
+                            ]
+                        },
+                        {
+                            "required": [
+                                "failure_side_waiver_approved_by"
+                            ]
+                        },
                         {
                             "required": [
                                 "rationale"

package/dist/search-answer.d.ts

@@ -218,8 +218,9 @@ export declare function buildSearchAnswer(prolog: Pick<PrologPort, "query">, mat
 /**
  * Hold the whole answer under `maxBytes`, marking it truncated when anything
  * is cut. In order: long titles, excerpts and details are clipped; ADR
- * excerpts are dropped, last rationale entry first; the least relevant
- * governing requirements are dropped;
+ * excerpts are dropped, last rationale entry first; each governing
+ * requirement keeps only its first scenario and test, last requirement first;
+ * the least relevant governing requirements are dropped;
  * list items are dropped (notes and side lists before the remaining
  * requirement's own lists, its verdict witnesses last); then the remaining
  * requirement's title and `via` are clipped. A verdict keeps its status when

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

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

package/dist/search-answer.js

@@ -20,6 +20,7 @@ const ANSWER_RELATIONSHIPS = [
     "specified_by",
     "verified_by",
     "validates",
+    "assumes",
     "implements",
     "constrains",
     "requires_property",
@@ -206,7 +207,7 @@ function factDetail(fact, schema) {
 }
 function edgesGoal(ids) {
     const idList = ids.map((id) => `'${escapeAtom(id)}'`).join(",");
-    return `findall([Rel,From,To], (member(Rel, [${ANSWER_RELATIONSHIPS.join(",")}]), kb_relationship(Rel, From, To), (member(From, [${idList}]); member(To, [${idList}]))), Edges)`;
+    return `kb_relationship_edges([${ANSWER_RELATIONSHIPS.join(",")}], [${idList}], Edges)`;
 }
 /**
  * For each predicate fact among `ids`, the argument names and key arguments
@@ -643,6 +644,10 @@ export async function buildSearchAnswer(prolog, matches, options = {}) {
     // A matched test may verify a scenario rather than a requirement; its
     // targets are resolved to their governing requirements after the loop.
     const testTargets = [];
+    // A matched fact that no requirement grounds may be the assumption of a
+    // requirement's scenario, such as its failure side; it is resolved through
+    // that scenario after the loop.
+    const assumedFacts = [];
     for (const [index, match] of seeds.entries()) {
         const id = text(match.entity.id);
         const entity = graph.row(id) ?? match.entity;
@@ -674,6 +679,19 @@ export async function buildSearchAnswer(prolog, matches, options = {}) {
             testTargets.push({ id, score: match.score, targets: owners });
             continue;
         }
+        if (type === "fact" && owners.length === 0) {
+            const scenarios = seedEdges
+                .filter((edge) => edge.rel === "assumes" && edge.to === id)
+                .map((edge) => edge.from);
+            if (scenarios.length > 0) {
+                assumedFacts.push({
+                    id,
+                    score: match.score,
+                    scenarios: unique(scenarios),
+                });
+                continue;
+            }
+        }
         if (owners.length === 0 && ["fact", "scenario", "symbol"].includes(type)) {
             // A fact's claim and ask are filled in once its schema is known.
             if (ungoverned.length < limits.ungoverned)
@@ -688,7 +706,10 @@ export async function buildSearchAnswer(prolog, matches, options = {}) {
     const byScore = () => [...candidates.entries()]
         .sort(([, left], [, right]) => right.score - left.score)
         .map(([id]) => id);
-    const targetIds = unique(testTargets.flatMap((test) => test.targets));
+    const targetIds = unique([
+        ...testTargets.flatMap((test) => test.targets),
+        ...assumedFacts.flatMap((fact) => fact.scenarios),
+    ]);
     // Test targets and the candidates found so far share one round trip.
     await graph.fetch({
         edges: [...targetIds, ...byScore()],
@@ -720,6 +741,22 @@ export async function buildSearchAnswer(prolog, matches, options = {}) {
                 propose(owner, test.score * 0.85, `test ${test.id} via ${target}`);
         }
     }
+    for (const fact of assumedFacts) {
+        const owners = fact.scenarios.flatMap((scenario) => targetEdges
+            .filter((edge) => edge.rel === "specified_by" && edge.to === scenario)
+            .map((edge) => ({ owner: edge.from, scenario })));
+        if (owners.length === 0) {
+            const row = graph.row(fact.id);
+            const rank = seedIds.indexOf(fact.id) + 1;
+            if (row !== null && ungoverned.length < limits.ungoverned)
+                ungoverned.push({ ...brief(row), type: "fact", rank });
+            else if (row !== null)
+                truncated = true;
+            continue;
+        }
+        for (const { owner, scenario } of owners)
+            propose(owner, fact.score * 0.85, `fact ${fact.id} via ${scenario}`);
+    }
     const supersededBy = new Map();
     for (const edge of seedEdges)
         if (edge.rel === "supersedes")
@@ -1035,8 +1072,9 @@ const REQUIREMENT_TRIM_ORDER = [
 /**
  * Hold the whole answer under `maxBytes`, marking it truncated when anything
  * is cut. In order: long titles, excerpts and details are clipped; ADR
- * excerpts are dropped, last rationale entry first; the least relevant
- * governing requirements are dropped;
+ * excerpts are dropped, last rationale entry first; each governing
+ * requirement keeps only its first scenario and test, last requirement first;
+ * the least relevant governing requirements are dropped;
  * list items are dropped (notes and side lists before the remaining
  * requirement's own lists, its verdict witnesses last); then the remaining
  * requirement's title and `via` are clipped. A verdict keeps its status when
@@ -1084,6 +1122,21 @@ export function fitSearchAnswer(answer, maxBytes = SEARCH_ANSWER_LIMITS.maxBytes
         rationale[index] = withoutExcerpt(rationale[index]);
         current = { ...current, rationale };
     }
+    // A requirement's second scenario or test matters less than another
+    // governing requirement: keep one of each, last requirement first, before
+    // dropping a requirement.
+    for (let index = current.governing.length - 1; index >= 0 && over(); index -= 1) {
+        const governing = [...current.governing];
+        const req = governing[index];
+        if (req.scenarios.length <= 1 && req.tests.length <= 1)
+            continue;
+        governing[index] = {
+            ...req,
+            scenarios: req.scenarios.slice(0, 1),
+            tests: req.tests.slice(0, 1),
+        };
+        current = { ...current, governing };
+    }
     while (over() && current.governing.length > 1)
         current = { ...current, governing: current.governing.slice(0, -1) };
     while (over()) {

package/dist/search-hints.d.ts

@@ -0,0 +1,58 @@
+import type { PluginProviderStamp, SearchHintsEntity, SearchHintsV1 } from "kibi-plugin-sdk";
+import { type IntentSearchAnalysis, type MarkdownBodyCache } from "./intent-search.js";
+import { type SearchHintsDiagnostic } from "./plugins/compose-search-hints.js";
+import type { CapabilityModeResolution } from "./plugins/registry.js";
+import type { PrologPort } from "./public/operations/runtime-types.js";
+/**
+ * Below this top score a lexical answer is weak enough to show hints. On
+ * Kibi's own KB, 17 of 18 reworded questions the ranker got wrong scored
+ * below it, against 6 of 30 gold questions it got right. Host-owned, so no
+ * provider can move it.
+ */
+export declare const SEARCH_HINT_WEAK_SCORE = 0.44;
+/** Requirements shown as hints. */
+export declare const SEARCH_HINT_LIMIT = 10;
+export type SearchHintsTrigger = "abstained" | "weak";
+export type SearchHintItem = Readonly<{
+    id: string;
+    title: string;
+    score: number;
+    /** The entity the provider matched, when the hint is its requirement. */
+    via?: string;
+}>;
+export type SearchHintsAnalysis = Readonly<{
+    trigger: SearchHintsTrigger;
+    provider: PluginProviderStamp | null;
+    items: readonly SearchHintItem[];
+    shadow?: readonly {
+        readonly provider: PluginProviderStamp;
+        readonly items: readonly {
+            readonly id: string;
+            readonly score: number;
+        }[];
+    }[];
+    diagnostics?: readonly SearchHintsDiagnostic[];
+}>;
+/** Why a lexical answer needs hints, or null when it is strong enough. */
+export declare function searchHintsTrigger(analysis: IntentSearchAnalysis): SearchHintsTrigger | null;
+/** The current entities a provider may hint at, as the search loaded them. */
+export declare function searchHintsEntities(entities: readonly Record<string, unknown>[], bodies: MarkdownBodyCache, workspaceRoot: string): SearchHintsEntity[];
+/**
+ * Ask the configured kibi.search-hints.v1 provider which current entities a
+ * weakly answered question is probably about. Returns undefined when the
+ * answer is strong or no provider is configured. Hints never change the
+ * ranked results, the governing answer or abstention.
+ */
+export declare function buildSearchHints(options: Readonly<{
+    query: string;
+    analysis: IntentSearchAnalysis;
+    entities: readonly Record<string, unknown>[];
+    bodies: MarkdownBodyCache;
+    governingIds: readonly string[];
+    resolution: CapabilityModeResolution<SearchHintsV1>;
+    prolog: Pick<PrologPort, "query">;
+    workspaceRoot: string;
+}>): Promise<SearchHintsAnalysis | undefined>;
+/** The sentence a search answer's text adds when hints are shown. */
+export declare function searchHintsNote(hints: SearchHintsAnalysis | undefined): string;
+//# sourceMappingURL=search-hints.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search-hints.d.ts","sourceRoot":"","sources":["../src/search-hints.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACd,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EAGvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,KAAK,qBAAqB,EAE3B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAEtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAIvE;;;;;GAKG;AAEH,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAC3C,mCAAmC;AAEnC,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAYpC,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,MAAM,CAAC;AAGtD,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC,CAAC;AAGH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACrC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IACjC,MAAM,CAAC,EAAE,SAAS;QAChB,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;QACvC,QAAQ,CAAC,KAAK,EAAE,SAAS;YAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;KAC5E,EAAE,CAAC;IACJ,WAAW,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAChD,CAAC,CAAC;AAEH,0EAA0E;AAE1E,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,oBAAoB,GAC7B,kBAAkB,GAAG,IAAI,CAG3B;AAwCD,8EAA8E;AAE9E,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC5C,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,MAAM,GACpB,iBAAiB,EAAE,CAiBrB;AAuDD;;;;;GAKG;AAEH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,QAAQ,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAC7C,MAAM,EAAE,iBAAiB,CAAC;IAC1B,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,UAAU,EAAE,wBAAwB,CAAC,aAAa,CAAC,CAAC;IACpD,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAClC,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC,GACD,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAgD1C;AAED,qEAAqE;AAErE,wBAAgB,eAAe,CAC7B,KAAK,EAAE,mBAAmB,GAAG,SAAS,GACrC,MAAM,CAOR"}