kibi-core 0.22.1 → 0.22.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-core",
-  "version": "0.22.1",
+  "version": "0.22.3",
   "private": false,
   "description": "Core Prolog modules and RDF graph logic for Kibi",
   "type": "module",

package/src/checks.pl

@@ -72,7 +72,7 @@
     check_subject_key_shape/1,
     check_ontology_quality/1
 ]).
-:- use_module('logic_ir.pl', [logic_rule_safety/2, logic_rule_from_props/2, logic_rule_render/2, logic_rule_conflict/3, logic_rule_conflict_witness/3, logic_rules_stratified/1, logic_rule_missing_keys/4, functional_predicate_declarations/1, logic_rule_property_form/2]).
+:- use_module('logic_ir.pl', [logic_rule_safety/2, logic_rule_from_props/2, logic_rule_render/2, logic_rule_conflict/3, logic_rule_conflict_witness/4, logic_rules_stratified/1, logic_rule_missing_keys/4, functional_predicate_declarations/1, logic_rule_property_form/2]).
 % GENERATED registry facts; single source is schema/rule-registry.json.
 :- use_module('rule_registry.pl', [known_rule/1]).
 
@@ -214,12 +214,97 @@ check_changed_symbol_coverage(ExtraSymbols, Violations) :-
 symbol_coverage_violation(SymbolId, violation(
     'symbol-coverage',
     SymbolId,
-    "Production symbol lacks qualifying requirement coverage.",
-    "Add 'covered_by: TEST-<area>-<behavior>' for production coverage. If the requirement has specified_by a scenario, use verified_by(scenario,test) or validates(test,scenario). Direct verified_by(req,test) does not count when a scenario exists.",
+    Description,
+    Suggestion,
     Source
 )) :-
+    symbol_coverage_message(SymbolId, Description, Suggestion),
     violation_source(SymbolId, symbol, Source).
 
+%% symbol_coverage_message(+SymbolId, -Description, -Suggestion)
+% A symbol with no covered_by gets the generic advice. A symbol that already
+% has covered_by is missing a different link: none of its tests verifies a
+% requirement, so the message names the tests, the requirement the symbol
+% implements and the relationship that would connect them.
+% implements REQ-kibi-symbol-link-guidance
+symbol_coverage_message(SymbolId, Description, Suggestion) :-
+    findall(Test, kb_relationship(covered_by, SymbolId, Test), Tests0),
+    sort(Tests0, Tests),
+    Tests = [Test|_],
+    !,
+    findall(Req,
+            ( kb_relationship(implements, SymbolId, Req),
+              kb_entity(Req, req, _)
+            ),
+            Reqs0),
+    sort(Reqs0, Reqs),
+    coverage_id_list(Tests, TestList),
+    coverage_id_text(SymbolId, Symbol),
+    (   Reqs = [Req|_]
+    ->  coverage_id_list(Reqs, ReqList),
+        (   Tests = [_]
+        ->  format(string(Description),
+                   "Production symbol lacks qualifying requirement coverage: ~w is covered_by ~w, but ~w does not verify ~w, which ~w implements.",
+                   [Symbol, TestList, TestList, ReqList, Symbol])
+        ;   format(string(Description),
+                   "Production symbol lacks qualifying requirement coverage: ~w is covered_by ~w, but none of them verifies ~w, which ~w implements.",
+                   [Symbol, TestList, ReqList, Symbol])
+        ),
+        covered_symbol_link_suggestion(Req, Test, Suggestion)
+    ;   format(string(Description),
+               "Production symbol lacks qualifying requirement coverage: ~w is covered_by ~w, but ~w implements no requirement and none of its tests verifies one.",
+               [Symbol, TestList, Symbol]),
+        coverage_id_text(Test, TestText),
+        format(string(Suggestion),
+               "Add implements(~w, REQ-...) for the requirement this symbol owns, then connect ~w to it: verified_by(SCEN-..., ~w) through the requirement's scenario, or verified_by(REQ-..., ~w) when the requirement has no scenario.",
+               [Symbol, TestText, TestText, TestText])
+    ).
+symbol_coverage_message(_SymbolId,
+    "Production symbol lacks qualifying requirement coverage.",
+    "Add 'covered_by: TEST-<area>-<behavior>' for production coverage. If the requirement has specified_by a scenario, use verified_by(scenario,test) or validates(test,scenario). Direct verified_by(req,test) does not count when a scenario exists.").
+
+%% covered_symbol_link_suggestion(+Req, +Test, -Suggestion)
+% The one relationship that would let Test cover Req, following the same
+% paths test_covers_requirement/2 accepts.
+covered_symbol_link_suggestion(Req, Test, Suggestion) :-
+    coverage_id_text(Req, ReqText),
+    coverage_id_text(Test, TestText),
+    findall(Scenario, kb_relationship(specified_by, Req, Scenario), Scenarios0),
+    sort(Scenarios0, Scenarios),
+    (   ( Scenarios == [],
+          ( kb_relationship(verified_by, Req, Test)
+          ; kb_relationship(validates, Test, Req)
+          )
+        ; member(Scenario, Scenarios),
+          scenario_verified_by_test(Scenario, Test)
+        )
+    ->  format(string(Suggestion),
+               "~w is linked to ~w, but its verification_scope or verification_perspective does not match what ~w requires; set those test fields to the required values.",
+               [TestText, ReqText, ReqText])
+    ;   Scenarios = [Scenario|_]
+    ->  coverage_id_text(Scenario, ScenarioText),
+        coverage_id_list(Scenarios, ScenarioList),
+        (   ( kb_relationship(verified_by, Req, Test)
+            ; kb_relationship(validates, Test, Req)
+            )
+        ->  Direct = " Direct verified_by(req,test) does not count while the requirement has a scenario."
+        ;   Direct = ""
+        ),
+        format(string(Suggestion),
+               "Add verified_by(~w, ~w) (~w is specified_by ~w), or validates(~w, ~w).~w",
+               [ScenarioText, TestText, ReqText, ScenarioList, TestText, ScenarioText, Direct])
+    ;   format(string(Suggestion),
+               "Add verified_by(~w, ~w) (~w has no scenario, so the direct link counts), or specify it with a scenario that ~w verifies.",
+               [ReqText, TestText, ReqText, TestText])
+    ).
+
+coverage_id_text(Id, Text) :-
+    normalize_term_atom(Id, Text).
+
+coverage_id_list(Ids, Text) :-
+    maplist(coverage_id_text, Ids, Texts),
+    atomic_list_concat(Texts, ', ', Text).
+
 %% check_symbol_traceability(+RequireAdr, -Violations)
 % Finds all symbols lacking direct requirement ownership:
 % - Every symbol must have at least one direct implements ownership path
@@ -2433,7 +2518,8 @@ check_domain_contradictions_and_witnesses(Violations, Witnesses) :-
 % disproven remains status=unresolved rather than becoming consistency.
 check_domain_contradiction_witnesses(Witnesses) :-
     findall(Witness, req_conflict_witness(_ReqA, _ReqB, Witness), GroundWitnesses),
-    findall(Witness, rule_contradiction_witness(Witness), RuleWitnesses),
+    functional_predicate_declarations(Functional),
+    findall(Witness, rule_contradiction_witness(Functional, Witness), RuleWitnesses),
     append(GroundWitnesses, RuleWitnesses, Witnesses0),
     sort(Witnesses0, Witnesses).
 
@@ -2622,9 +2708,9 @@ opposing_rule_requirement_facts(ReqA, ReqB, FactA, FactB, RuleA, RuleB) :-
     logic_rule_from_props(PropsA, RuleA),
     logic_rule_from_props(PropsB, RuleB).
 
-rule_contradiction_witness(Witness) :-
+rule_contradiction_witness(Functional, Witness) :-
     opposing_rule_requirement_facts(ReqA, ReqB, FactA, FactB, RuleA, RuleB),
-    logic_rule_conflict_witness(RuleA, RuleB, InternalWitness),
+    logic_rule_conflict_witness(RuleA, RuleB, Functional, InternalWitness),
     InternalWitness.status \= disjoint,
     rule_conflict_side(ReqA, FactA, Left),
     rule_conflict_side(ReqB, FactB, Right),

package/src/logic_ir.pl

@@ -12,6 +12,7 @@
     logic_rule_conflict/3,
     logic_rule_conflict/4,
     logic_rule_conflict_witness/3,
+    logic_rule_conflict_witness/4,
     logic_rule_missing_keys/4,
     functional_predicate_declarations/1,
     logic_atom_signature/2,
@@ -1215,7 +1216,15 @@ dependency_path(Current, Target, Edges, Seen) :-
 % Consumers can attach requirement IDs and source spans without ever treating
 % the rendered Prolog preview as executable source.
 logic_rule_conflict_witness(RuleA, RuleB, Witness) :-
-    logic_rule_conflict(RuleA, RuleB, Status),
+    functional_predicate_declarations(Functional),
+    logic_rule_conflict_witness(RuleA, RuleB, Functional, Witness).
+
+%% logic_rule_conflict_witness(+RuleA, +RuleB, +Functional, -Witness)
+% As logic_rule_conflict_witness/3 with the functional declarations already
+% read.  Reading them scans every predicate_schema fact, so a caller walking
+% every opposing rule pair reads them once instead of once per pair.
+logic_rule_conflict_witness(RuleA, RuleB, Functional, Witness) :-
+    logic_rule_conflict(RuleA, RuleB, Functional, Status),
     RuleA = rule(_KindA, ModalityA, HeadA, BodyA, ExceptionsA, ScopeA, FromA, ToA, SchemaA, _VariablesA),
     RuleB = rule(_KindB, ModalityB, HeadB, BodyB, ExceptionsB, ScopeB, FromB, ToB, SchemaB, _VariablesB),
     Witness = witness{

package/src/rule_registry.pl

@@ -62,6 +62,7 @@ known_rule('entity-context-missing').
 known_rule('entity-context-acknowledged').
 known_rule('decision-firm-unreferenced').
 known_rule('decision-firm-superseded').
+known_rule('decision-firm-edited').
 known_rule('supersedes-reason-missing').
 known_rule('supersedes-reason-acknowledged').
 known_rule('policy-ownership').
@@ -115,6 +116,7 @@ rule_enforcement_class('entity-context-missing', canonical).
 rule_enforcement_class('entity-context-acknowledged', advisory).
 rule_enforcement_class('decision-firm-unreferenced', canonical).
 rule_enforcement_class('decision-firm-superseded', canonical).
+rule_enforcement_class('decision-firm-edited', canonical).
 rule_enforcement_class('supersedes-reason-missing', canonical).
 rule_enforcement_class('supersedes-reason-acknowledged', advisory).
 rule_enforcement_class('policy-ownership', canonical).
@@ -168,6 +170,7 @@ rule_implementation('entity-context-missing', typescript).
 rule_implementation('entity-context-acknowledged', typescript).
 rule_implementation('decision-firm-unreferenced', typescript).
 rule_implementation('decision-firm-superseded', typescript).
+rule_implementation('decision-firm-edited', typescript).
 rule_implementation('supersedes-reason-missing', typescript).
 rule_implementation('supersedes-reason-acknowledged', typescript).
 rule_implementation('policy-ownership', typescript).
@@ -291,6 +294,7 @@ rule_description('entity-context-missing', 'A current requirement, scenario, tes
 rule_description('entity-context-acknowledged', 'Informational: how many current entities carry the review:context-missing tag, so the legacy context backlog stays visible; one summary finding per check').
 rule_description('decision-firm-unreferenced', 'A requirement or ADR marked firmness: firm must name the human words it rests on: origin.ref (or approval_ref on a requirement); Kibi checks that the reference is present, not that it is genuine').
 rule_description('decision-firm-superseded', 'A requirement or ADR that supersedes a firm decision, retired or not, must itself be firm (and so carry a ref to the human who changed the rule); a default or exploratory replacement cannot overrule a firm decision').
+rule_description('decision-firm-edited', 'A current requirement or ADR that was firm at HEAD must not have its claim (title, stated meaning, the statement its body derives, an ADR\'s body, or its firmness) changed in place unless the edit cites new human words (a changed origin.ref, or approval_ref on a requirement); supersede it with a firm decision instead').
 rule_description('supersedes-reason-missing', 'A current requirement or ADR that supersedes another must explain why under a \'Why this changed\' heading (at least 12 words of prose naming the evidence and answering the old decision\'s reasoning); supersede edges recorded before schema 9 are acknowledged in the manifest and exempt').
 rule_description('supersedes-reason-acknowledged', 'Informational: how many current superseding requirements and ADRs have only supersede edges the schema 9 migration acknowledged without a \'Why this changed\' section; one summary finding per check').
 rule_description('policy-ownership', 'When a plugin activated for kibi.check-policy.v1 declares ownership rules, every production symbol in a rule\'s file set must implement a current requirement grounded (requires_predicate) in one of the rule\'s predicates; projects without an activated check policy are unaffected').