kibi-cli 2.21.0 → 2.21.2

package/dist/public/schemas/entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/public/schemas/entity.ts"],"names":[],"mappings":"AAwTA,QAAA,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CA4ZzC,CAAC;AAEF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/public/schemas/entity.ts"],"names":[],"mappings":"AAwTA,QAAA,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAwazC,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/dist/public/schemas/entity.js

@@ -333,6 +333,11 @@ const entitySchema = {
         text_ref: { type: "string" },
         // Provenance of any authored entity: who wrote it and on what authority.
         origin: ENTITY_ORIGIN_SCHEMA,
+        firmness: {
+            type: "string",
+            enum: ["firm", "default", "exploratory"],
+            description: "Requirement and ADR only. How firmly the decision was made. firm: a human stated it as a rule; it needs a ref (origin.ref, or approval_ref on a requirement) to their words, and only a human may change it. default (assumed when absent): a delegated or agent choice; a later agent may supersede it with evidence. exploratory: a flagged guess, expected to be revisited.",
+        },
         expects: {
             type: "string",
             enum: ["success", "rejection", "error"],
@@ -680,6 +685,12 @@ const entitySchema = {
                 },
             },
         },
+        {
+            if: {
+                properties: { type: { enum: ["req", "adr"] } },
+            },
+            else: { not: { required: ["firmness"] } },
+        },
         {
             if: {
                 properties: { type: { const: "scenario" } },

package/dist/public/skills/kibi-traceability/SKILL.md

@@ -43,10 +43,12 @@ sequential `kb_upsert`, then run final check and coverage. Kibi authors tracked
 files transactionally but never Git-stages or commits them. Do not read or edit
 `.kb` directly.
 
-Use `kb_delete` only for intentional cleanup. Authored entity deletion returns a
-hash-bound approval plan; requirements normally evolve through a new
-requirement linked with `supersedes`. Relationship deletes patch shards while
-preserving unrelated records.
+Use `kb_delete` only for intentional cleanup; `dryRun: true` previews any
+delete without writing. Authored entity deletion returns `outcome:
+plan_returned` with a hash-bound plan whose `nextActions[0].input` is the exact
+`kb_apply_plan` input; requirements return `supersession_required` and evolve
+through a new requirement linked with `supersedes`. Relationship deletes patch
+shards while preserving unrelated records.
 
 ## Typed recovery and proof
 

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.15.3
+version: 2.16.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -188,8 +188,9 @@ returns `status: error`, `MIGRATION_PLAN_REFUSED` and `data.outcome:
 refused`: nothing changed, so read the action `detail` and get a new plan.
 `data.outcome: reconciliation_required` (status success) means an action
 failed mid-way: inspect its effect before retrying. `kb_delete` of an
-authored entity returns status success with `deleted: 0`; its `errors` say
-why nothing was deleted. If the status is
+authored entity returns status success with `deleted: 0` and `outcome:
+plan_returned` (or `supersession_required` for a requirement): nothing was
+deleted yet, and `nextActions` names the call that does it. If the status is
 `committed_with_repairs`, the mutation already committed: inspect failed effects,
 execute each required repair action in order, and never retry the original
 operation. Record effect failures, followed actions, and unsafe retries in
@@ -302,12 +303,18 @@ authored. Each one is the order the write path accepts.
    between the two writes `kb_check` reports the requirement until the
    second lands.
 3. **Deleting authored entities.** `kb_delete` on an authored entity that
-   is not a requirement (scenario, test, fact, ADR, …) returns a hash-bound
-   `kibi.entity-deletion-plan.v1` in `deletionPlan`; apply it unchanged with
-   `kb_apply_plan` (`plan` plus `approvedPlanHash: plan.planHash`). For an
-   authored requirement the plan carries `supersessionRequired: true` and
-   `kb_apply_plan` refuses it (`REQUIREMENT_SUPERSESSION_REQUIRED`): Kibi
-   never deletes an authored requirement. Evolve it instead with a new
+   is not a requirement (scenario, test, fact, ADR, …) writes nothing and
+   returns `outcome: plan_returned` with a hash-bound
+   `kibi.entity-deletion-plan.v1` in `deletionPlan`. After review, run
+   `nextActions[0]` unchanged: `kb_apply_plan` with its `input` (`plan` plus
+   `approvedPlanHash: plan.planHash`), or repeat the `kb_delete` call with
+   `approvedPlanHash` to apply the freshly computed plan in one step (a
+   changed source fails with `DELETE_PLAN_HASH_MISMATCH`). `dryRun: true`
+   previews relationship and direct deletes without writing. For an
+   authored requirement the result is `outcome: supersession_required`, the
+   plan carries `supersessionRequired: true` and both routes refuse it
+   (`REQUIREMENT_SUPERSESSION_REQUIRED`): Kibi never deletes an authored
+   requirement. Evolve it instead with a new
    requirement linked by `supersedes` and close the old one, or, for an
    agent-origin requirement nobody approved and nothing links to, upsert it
    with `status: closed` (keep its `title`); it stays on disk as history. A
@@ -342,6 +349,29 @@ 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.
 
+## Decision firmness
+
+Requirements and ADRs carry `firmness`, which says what you may do with them.
+Search answers, `kb_query` rows and hook snippets show it (snippets label only
+`[firm]` and `[exploratory]`; an unlabeled decision is `default`).
+
+- `firm`: a human stated it as a rule. Follow it; to change it, ask first.
+  `kb_check` blocks a firm decision without `origin.ref` to their words, and
+  a replacement of a firm decision that is not itself firm.
+- `default` (when absent): a delegated or agent choice. Follow it unless the
+  task gives evidence against it; then supersede it in the same change and
+  list it under "Decisions I changed" for review, without asking first.
+- `exploratory`: a flagged guess; revisit it when you touch the area.
+
+Set `firmness` from what a human actually said: only their stated rule is
+`firm` (with `origin.ref`); "do whatever" or your own pick is `default`; a
+guess is `exploratory`. A supersede needs `## Why this changed` in the new
+entity's body (at least 12 words): name the evidence (a failing test, a
+measured cost, a constraint the old decision missed, a new requirement) and
+answer the old decision's reasoning; `kb_check` blocks it otherwise. A
+preference is not evidence: propose it instead of superseding. Kibi checks
+only that a firm decision has a reference; never cite words nobody said.
+
 Conditional clauses ("only when", "only if", "must not ... unless") compile
 into typed `forbid` rules linked by `requires_rule`, not property facts; one
 `kb_model` or `kb_compile_intent` cannot translate stays an `ontology_gap`.
@@ -421,7 +451,17 @@ a second grounding link would fail, so keep the existing link or apply the
 `kb_delete` of the old link, requirement link; between the last two `kb_check`
 reports both `logic-coverage` and `strict-req-fact-pairing` for the
 requirement, as `expected.kbCheckAfterStep` states; run `kb_check` after the
-last step and apply `rollback` if it is not clean); `provide_argument_bindings` and `record_ontology_gap` mean
+last step and apply `rollback` if it is not clean). `keep_existing_grounding`
+means the requirement already links a predicate fact with the candidate's
+`canonical_key` (`existingGrounding[].matchedBy` is `canonical_key` when the
+claim was worded differently), so write nothing. `extend_requirement` means
+the requirement's proposition ledger has no entry for this text, so a link
+cannot be made and no fact is planned: add the clause to the requirement's
+prose (`mode: "requirement"`, or `kb_upsert` with the extended `semantic_text`
+and the ledger `mode: "analyze"` returns) and call `mode: "predicates"` again.
+Read `decisionConflicts` and its warnings whenever `plan` is null: they name
+the stored decision facts the candidate would contradict and the requirements
+that own them. `provide_argument_bindings` and `record_ontology_gap` mean
 the same as for an ungrounded claim, and the gap observation is not a grounding
 link, so write it exactly as returned (tags, `claim_text`, `document.body`, no
 `claim_key`, no relationships). Record an ontology gap only when no returned schema fits the

package/dist/public/skills/kibi-usage/resources/source-authoring.md

@@ -23,8 +23,10 @@ drift diagnostic. Unresolved Git index conflicts are likewise blocking; Kibi
 never chooses a merge winner.
 
 Relationship upserts and relationship deletes patch only the canonical shard,
-preserving unrelated records. Authored entity deletion returns a hash-bound
-plan; approve that plan through `kb_apply_plan`. Evolve requirements with a new
+preserving unrelated records. Authored entity deletion writes nothing and
+returns a hash-bound plan (`outcome: plan_returned`); approve it by running the
+returned `nextActions[0]` (`kb_apply_plan` with `{plan, approvedPlanHash}`)
+unchanged, or by repeating `kb_delete` with `approvedPlanHash`. Evolve requirements with a new
 requirement and `supersedes`, rather than deleting the old semantic claim.
 
 On `committed_with_repairs`, inspect `effects` and execute the typed required

package/dist/relationships/shards.d.ts

@@ -61,6 +61,16 @@ export type RemovedRelationshipRecords = Readonly<{
  * approve the bytes before writing (deletion plans) render without writing.
  */
 export declare function renderShardWithout(text: string, selectors: readonly RelationshipSelector[], shardPath: string): string;
+export type PlannedShardRemovals = Readonly<{
+    removals: RemovedRelationshipRecords[];
+    /** Shard path -> its body without the selected records. */
+    bodies: ReadonlyMap<string, string>;
+}>;
+/**
+ * Render every shard that holds a selected relationship without writing it,
+ * so a dry run can report the exact bytes a delete would publish.
+ */
+export declare function planRelationshipShardRemovals(kbRoot: string, selectors: readonly RelationshipSelector[]): PlannedShardRemovals;
 export declare function removeRelationshipsFromShards(kbRoot: string, selectors: readonly RelationshipSelector[]): RemovedRelationshipRecords[];
 /**
  * Appends a relationship to the appropriate shard.

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

@@ -197,15 +197,21 @@ export function renderShardWithout(text, selectors, shardPath) {
     }
     return document.toString();
 }
-export function removeRelationshipsFromShards(kbRoot, selectors) {
+/**
+ * Render every shard that holds a selected relationship without writing it,
+ * so a dry run can report the exact bytes a delete would publish.
+ */
+// implements REQ-kibi-operation-interface-parity
+export function planRelationshipShardRemovals(kbRoot, selectors) {
     const wanted = new Set(selectors.map((selector) => `${selector.type}\0${selector.from}\0${selector.to}`));
     const removed = new Map();
+    const bodies = new Map();
     for (const shardPath of listShards(kbRoot)) {
         const records = readShard(shardPath);
         const matching = records.filter((record) => wanted.has(`${record.type}\0${record.from}\0${record.to}`));
         if (matching.length === 0)
             continue;
-        atomicWriteText(shardPath, renderShardWithout(fs.readFileSync(shardPath, "utf8"), selectors, shardPath));
+        bodies.set(shardPath, renderShardWithout(fs.readFileSync(shardPath, "utf8"), selectors, shardPath));
         for (const record of matching) {
             const key = `${record.type}\0${record.from}\0${record.to}`;
             const entry = removed.get(key) ?? { paths: [], sources: [] };
@@ -214,15 +220,25 @@ export function removeRelationshipsFromShards(kbRoot, selectors) {
             removed.set(key, entry);
         }
     }
-    return selectors.map((selector) => {
-        const entry = removed.get(`${selector.type}\0${selector.from}\0${selector.to}`);
-        return {
-            selector,
-            shardPaths: entry?.paths ?? [],
-            sources: entry?.sources ?? [],
-            removed: entry !== undefined,
-        };
-    });
+    return {
+        bodies,
+        removals: selectors.map((selector) => {
+            const entry = removed.get(`${selector.type}\0${selector.from}\0${selector.to}`);
+            return {
+                selector,
+                shardPaths: entry?.paths ?? [],
+                sources: entry?.sources ?? [],
+                removed: entry !== undefined,
+            };
+        }),
+    };
+}
+export function removeRelationshipsFromShards(kbRoot, selectors) {
+    const planned = planRelationshipShardRemovals(kbRoot, selectors);
+    for (const [shardPath, body] of planned.bodies) {
+        atomicWriteText(shardPath, body);
+    }
+    return planned.removals;
 }
 /**
  * Serializes records to YAML format.

package/dist/schemas/entity.schema.json

@@ -514,6 +514,15 @@
             },
             "additionalProperties": false
         },
+        "firmness": {
+            "type": "string",
+            "enum": [
+                "firm",
+                "default",
+                "exploratory"
+            ],
+            "description": "Requirement and ADR only. How firmly the decision was made. firm: a human stated it as a rule; it needs a ref (origin.ref, or approval_ref on a requirement) to their words, and only a human may change it. default (assumed when absent): a delegated or agent choice; a later agent may supersede it with evidence. exploratory: a flagged guess, expected to be revisited."
+        },
         "expects": {
             "type": "string",
             "enum": [
@@ -1657,6 +1666,25 @@
                 }
             }
         },
+        {
+            "if": {
+                "properties": {
+                    "type": {
+                        "enum": [
+                            "req",
+                            "adr"
+                        ]
+                    }
+                }
+            },
+            "else": {
+                "not": {
+                    "required": [
+                        "firmness"
+                    ]
+                }
+            }
+        },
         {
             "if": {
                 "properties": {

package/dist/search-answer.d.ts

@@ -1,3 +1,4 @@
+import { type Firmness } from "./decision-firmness.js";
 import type { IntentSearchMatch } from "./intent-search.js";
 import type { PrologPort } from "./public/operations/runtime-types.js";
 /**
@@ -19,6 +20,12 @@ export type SearchAnswerEntity = Readonly<{
     id: string;
     title: string;
     status?: string;
+    /**
+     * Requirements and ADRs: how firmly the decision was made. `firm` (a human
+     * stated it; ask before changing), `default` (supersede it with evidence),
+     * `exploratory` (a guess to revisit).
+     */
+    firmness?: Firmness;
 }>;
 /**
  * A test verifying a governing requirement. `via` is `"direct"` for a test
@@ -69,8 +76,13 @@ export type SearchAnswerException = SearchAnswerEntity & Readonly<{
 /**
  * A linked fact says what it states in its typed form, so an agent can read
  * `has_role(alice, admin)` or `user.role_assignment max_roles lte 2` without
- * opening the entity, and `ask` is the exact kb_query that answers precise
- * questions about the same predicate or subject.
+ * opening the entity, and `ask` is the kb_query that reproduces the fact's
+ * own tuple as precisely as kb_query supports: a property or subject fact by
+ * its keys; a predicate fact by name plus, when a project `predicate_schema`
+ * or the built-in signature declares its arguments, `where` over the key
+ * arguments (the declared `key_arguments`, else the argument named `subject`,
+ * else the first), otherwise its full positional `args`. Pasted, it returns
+ * the fact and only facts sharing those key arguments.
  */
 export type SearchAnswerFact = SearchAnswerEntity & Readonly<{
     factKind?: string;
@@ -142,6 +154,23 @@ export declare const SEARCH_ANSWER_LIMITS: {
     /** Characters of a witness or unknown detail kept. */
     readonly detailChars: 240;
 };
+/**
+ * The declared arguments of a predicate fact's schema: a project
+ * `predicate_schema` or the built-in signature kb_query resolves `where`
+ * names against. `keyArguments` is empty when the schema declares none.
+ */
+export type PredicateFactSchema = Readonly<{
+    argumentNames: readonly string[];
+    keyArguments: readonly string[];
+}>;
+/**
+ * The `where` filter that selects the facts sharing a predicate fact's key
+ * arguments: the schema's `key_arguments`, else the argument named `subject`,
+ * else the first argument. Undefined when the schema does not fit the fact
+ * (arity) or no key argument has a value, so the caller falls back to
+ * positional args.
+ */
+export declare function predicateKeyFilter(args: readonly string[], schema: PredicateFactSchema): Record<string, string> | undefined;
 /**
  * The opening sentences of an ADR's Decision section (falling back to
  * Rationale, then to the first prose paragraph), as plain text of at most

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

@@ -1,4 +1,5 @@
-import { escapeAtom, normalizeEntityId, parseEntityFromList, parseListOfLists, parseTriples, } from "./prolog/codec.js";
+import { effectiveFirmness } from "./decision-firmness.js";
+import { escapeAtom, normalizeEntityId, parseAtomList, parseEntityFromList, parseListOfLists, parseTriples, } from "./prolog/codec.js";
 import { isProvenanceStub } from "./provenance-stub.js";
 import { entityRowsGoal } from "./public/operations/discovery-entities.js";
 import { runOperationJsonQuery } from "./public/operations/prolog-json.js";
@@ -41,6 +42,7 @@ const ROW_KEYS = [
     "status",
     "fact_kind",
     "approved_by",
+    "firmness",
     "source",
     "sourceFile",
     "predicate_namespace",
@@ -84,30 +86,68 @@ function unique(ids) {
 }
 function brief(entity) {
     const status = text(entity.status);
+    const firmness = effectiveFirmness(entity.type, entity.firmness);
     return {
         id: text(entity.id),
         title: text(entity.title),
         ...(status ? { status } : {}),
+        ...(firmness ? { firmness } : {}),
     };
 }
 function queryCall(args) {
     return `kb_query(${JSON.stringify(args)})`;
 }
+/**
+ * The `where` filter that selects the facts sharing a predicate fact's key
+ * arguments: the schema's `key_arguments`, else the argument named `subject`,
+ * else the first argument. Undefined when the schema does not fit the fact
+ * (arity) or no key argument has a value, so the caller falls back to
+ * positional args.
+ */
+// implements REQ-kibi-query-fact-filters
+export function predicateKeyFilter(args, schema) {
+    const names = schema.argumentNames;
+    if (names.length === 0 || names.length !== args.length)
+        return undefined;
+    const declared = schema.keyArguments.filter((key) => names.includes(key));
+    const keys = declared.length > 0
+        ? declared
+        : [names.includes("subject") ? "subject" : names[0]];
+    const where = {};
+    for (const key of keys) {
+        const value = args[names.indexOf(key)] ?? "";
+        if (value !== "")
+            where[key] = value;
+    }
+    return Object.keys(where).length > 0 ? where : undefined;
+}
 /** Typed statement and follow-up query of a linked fact, by fact kind. */
 // implements REQ-kibi-query-fact-filters
-function factDetail(fact) {
+function factDetail(fact, schema) {
     const factKind = text(fact.fact_kind);
     const base = factKind ? { factKind } : {};
     const predicate = text(fact.predicate_name);
     if (factKind === "predicate" && predicate) {
         const args = Array.isArray(fact.predicate_args)
-            ? fact.predicate_args.map(text).join(", ")
-            : text(fact.predicate_args);
+            ? fact.predicate_args.map(text)
+            : undefined;
         const polarity = text(fact.polarity) === "deny" ? " [deny]" : "";
+        const namespace = text(fact.predicate_namespace);
+        const call = {
+            predicate,
+            ...(namespace && namespace !== "default" ? { namespace } : {}),
+        };
+        if (args !== undefined && args.length > 0) {
+            const where = schema ? predicateKeyFilter(args, schema) : undefined;
+            if (where)
+                call.where = where;
+            else
+                call.args = args.map((value) => (value === "" ? null : value));
+        }
         return {
             ...base,
-            claim: `${predicate}(${args})${polarity}`,
-            ask: queryCall({ predicate }),
+            claim: `${predicate}(${args?.join(", ") ?? text(fact.predicate_args)})${polarity}`,
+            ask: queryCall(call),
         };
     }
     const subjectKey = text(fact.subject_key);
@@ -128,6 +168,27 @@ 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)`;
 }
+/**
+ * For each predicate fact among `ids`, the argument names and key arguments
+ * of the schema kb_query resolves its `where` names against: the project
+ * `predicate_schema` of its namespace and name, else the built-in signature.
+ * Facts of other kinds, and predicates without a schema, yield no row.
+ */
+// implements REQ-kibi-query-fact-filters
+function factSchemasGoal(ids) {
+    const idList = ids.map((id) => `'${escapeAtom(id)}'`).join(",");
+    return `findall([FactId,Names,Keys], (member(FactId, [${idList}]), kb:predicate_fact(FactId, Ns, Name, _, _), ((kb:predicate_schema(SchemaId, Ns, Name, _, Names, _) -> ((kb_entity(SchemaId, fact, Props), memberchk(key_arguments=KeysRaw, Props), kb:normalize_term_atom_list(KeysRaw, Keys)) -> true ; Keys = [])) ; (kb:builtin_decision_predicate(Ns, Name, _, KeyPositions, _), kb:builtin_predicate_signature(Name, _, Names), findall(Key, (member(P, KeyPositions), nth1(P, Names, Key)), Keys)))), Schemas)`;
+}
+function parseFactSchemas(raw) {
+    const schemas = new Map();
+    for (const [id, names, keys] of parseTriples(raw ?? "[]")) {
+        schemas.set(normalizeEntityId(id), {
+            argumentNames: parseAtomList(names),
+            keyArguments: parseAtomList(keys),
+        });
+    }
+    return schemas;
+}
 /**
  * The part of the KB graph the answer reads, fetched in batches: each
  * `fetch` is one engine round trip for every id whose edges or row are not
@@ -489,6 +550,29 @@ async function fetchVerdicts(prolog, graph, rowIds, reqIds) {
         return undefined;
     }
 }
+/**
+ * The rows the answer still needs plus the schemas of the predicate facts
+ * among `factIds`, in one round trip. A schema lookup the engine cannot run
+ * leaves the rows loaded and every ask positional.
+ */
+// implements REQ-kibi-query-fact-filters
+async function fetchFactSchemas(graph, factIds, request) {
+    if (factIds.length === 0) {
+        await graph.fetch(request);
+        return new Map();
+    }
+    try {
+        const bindings = await graph.fetch({
+            ...request,
+            alsoGoal: factSchemasGoal(factIds),
+        });
+        return parseFactSchemas(bindings.Schemas);
+    }
+    catch {
+        await graph.fetch(request);
+        return new Map();
+    }
+}
 // implements REQ-bootstrap-provenance-stubs
 export async function buildSearchAnswer(prolog, matches, options = {}) {
     const limits = SEARCH_ANSWER_LIMITS;
@@ -551,13 +635,9 @@ export async function buildSearchAnswer(prolog, matches, options = {}) {
             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)
-                ungoverned.push({
-                    ...brief(entity),
-                    ...(type === "fact" ? factDetail(entity) : {}),
-                    type,
-                    rank: index + 1,
-                });
+                ungoverned.push({ ...brief(entity), type, rank: index + 1 });
             else
                 truncated = true;
             continue;
@@ -689,7 +769,13 @@ export async function buildSearchAnswer(prolog, matches, options = {}) {
             exceptions: firstOf(into("exempts")),
         };
     });
-    await graph.fetch({
+    // The schemas of the linked and ungoverned predicate facts share this
+    // round trip, so each fact's ask can name its key arguments.
+    const factIds = unique([
+        ...ungoverned.filter((entry) => entry.type === "fact").map((e) => e.id),
+        ...plans.flatMap((plan) => plan.facts),
+    ]);
+    const schemas = await fetchFactSchemas(graph, factIds, {
         edges: plans.flatMap((plan) => plan.scenarios),
         rows: plans.flatMap((plan) => [
             ...plan.facts,
@@ -699,6 +785,18 @@ export async function buildSearchAnswer(prolog, matches, options = {}) {
             ...plan.directTests.slice(0, limits.perRequirement),
         ]),
     });
+    const detailedUngoverned = ungoverned.map((entry) => {
+        const row = entry.type === "fact" ? graph.row(entry.id) : null;
+        if (row === null)
+            return entry;
+        const { type, rank } = entry;
+        return {
+            ...brief(row),
+            ...factDetail(row, schemas.get(entry.id)),
+            type,
+            rank,
+        };
+    });
     // Tests linked to the requirement itself come first, then tests that
     // verify one of its scenarios; a test reached both ways counts as direct.
     const testVias = plans.map((plan) => {
@@ -738,7 +836,7 @@ export async function buildSearchAnswer(prolog, matches, options = {}) {
             via: req.via,
             facts: rowsOf(plan.facts).map((fact) => ({
                 ...brief(fact),
-                ...factDetail(fact),
+                ...factDetail(fact, schemas.get(text(fact.id))),
             })),
             scenarios: rowsOf(plan.scenarios).map(brief),
             tests: rowsOf(testIds[index] ?? []).map((row) => ({
@@ -769,17 +867,17 @@ export async function buildSearchAnswer(prolog, matches, options = {}) {
             ? verdicts.scope.syncedAt
             : null,
     };
-    ungoverned.sort((left, right) => left.rank - right.rank);
+    detailedUngoverned.sort((left, right) => left.rank - right.rank);
     const answer = {
         version: "kibi.search-answer.v1",
         governing,
         rationale,
         notGoverning,
         observations: observations.slice(0, limits.observations),
-        ungoverned,
+        ungoverned: detailedUngoverned,
         scope,
         truncated: truncated || graph.truncated,
-        note: answerNote(governing.length, ungoverned),
+        note: answerNote(governing.length, detailedUngoverned),
     };
     return fitSearchAnswer(answer, limits.maxBytes);
 }

package/dist/types/entities.d.ts

@@ -67,6 +67,8 @@ export type Requirement = BaseEntity & {
     approval_ref?: string;
     /** Why the requirement exists; explanation, not checked meaning. */
     rationale?: string;
+    /** How firmly it was decided; absent reads as default. */
+    firmness?: "firm" | "default" | "exploratory";
     /** Exception requirements only: claim keys of the exempted requirement it waives. */
     exempts_claims?: string[];
 };
@@ -78,6 +80,8 @@ export type TestEntity = BaseEntity & TestVerificationFields & {
 };
 export type ADR = BaseEntity & {
     type: "adr";
+    /** How firmly it was decided; absent reads as default. */
+    firmness?: "firm" | "default" | "exploratory";
 };
 export type Flag = BaseEntity & {
     type: "flag";

package/dist/types/entities.d.ts.map

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

package/dist/utils/kb-manifest.d.ts

@@ -20,6 +20,12 @@ export interface KbManifest {
      * Only these ids may carry `review:context-missing` without a violation.
      */
     contextAcknowledged?: string[];
+    /**
+     * Supersede edges (`FROM -> TO`) the schema 9 migration acknowledged as
+     * lacking a "Why this changed" section. An entity is exempt from
+     * supersedes-reason-missing only while every edge it has is listed here.
+     */
+    supersedesReasonAcknowledged?: string[];
 }
 export declare function defaultKbManifest(): KbManifest;
 export type KbManifestStatus = {