kibi-core 0.21.0 → 0.22.0

package/package.json

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

package/schema/entities.pl

@@ -51,6 +51,10 @@ entity_property(req, approval_ref, string).
 entity_property(req, rationale, string).
 % Claim keys of the exempted requirement an exception waives (all when absent).
 entity_property(req, exempts_claims, list).
+% How firmly a requirement or ADR was decided: firm, default or exploratory.
+% Absent reads as default.
+entity_property(req, firmness, atom).
+entity_property(adr, firmness, atom).
 % Intended outcome of a scenario: success, rejection or error.
 entity_property(scenario, expects, atom).
 
@@ -143,6 +147,8 @@ optional_property(req, approved_by).
 optional_property(req, approval_ref).
 optional_property(req, rationale).
 optional_property(req, exempts_claims).
+optional_property(req, firmness).
+optional_property(adr, firmness).
 optional_property(test, verification_scope).
 optional_property(test, verification_perspective).
 optional_property(test, proof_contract).

package/src/checks.pl

@@ -9,6 +9,7 @@
     check_selected_json/2,           % Returns only selected rule violations as JSON
     check_must_priority_coverage/1, % Returns list of must-priority violations
     check_symbol_coverage/1,        % Returns list of uncovered symbols
+    check_changed_symbol_coverage/2, % symbol-coverage restricted to a staged change set
     check_symbol_traceability/2,    % Returns list of symbols lacking requirement traceability (ReqAdr option)
     check_proof_contract_symbols/1, % Returns unresolved or unexpected required_proofs symbol issues
     check_no_dangling_refs/1,       % Returns list of dangling ref violations
@@ -198,6 +199,18 @@ check_symbol_coverage(Violations) :-
     sort(SymbolIds0, SymbolIds),
     maplist(symbol_coverage_violation, SymbolIds, Violations).
 
+%% check_changed_symbol_coverage(+ExtraSymbols, -Violations)
+% The symbol-coverage rule for the staged gate: the same violations
+% check_symbol_coverage/1 reports, restricted to the changed symbols
+% (kb:changed_symbol/1 overlay facts plus ExtraSymbols).
+% implements REQ-014
+check_changed_symbol_coverage(ExtraSymbols, Violations) :-
+    findall(SymbolId,
+            changed_symbol_no_req_coverage(ExtraSymbols, SymbolId),
+            SymbolIds0),
+    sort(SymbolIds0, SymbolIds),
+    maplist(symbol_coverage_violation, SymbolIds, Violations).
+
 symbol_coverage_violation(SymbolId, violation(
     'symbol-coverage',
     SymbolId,

package/src/discovery.pl

@@ -708,14 +708,18 @@ ask_schema_dict(Namespace, Name, SchemaDict, ArgumentNames) :-
     ArgumentNames = SchemaDict.argumentNames.
 ask_schema_dict(_Namespace, _Name, null, none).
 
+% A built-in row carries the catalog id that kb_model accepts as schemaId;
+% `stored: false` says no entity with that id exists, so it is not a
+% kb_query id.
 ask_builtin_schema_row(Namespace, Name, Arity, KeyPositions, DecisionPosition, Row) :-
-    builtin_argument_names(Name, Names),
+    kb:builtin_predicate_signature(Name, SchemaId, Names),
     findall(Key, (member(P, KeyPositions), nth1(P, Names, Key)), KeyArguments),
     nth1(DecisionPosition, Names, DecisionArgument),
     aggregate_all(count, kb:predicate_fact(_, Namespace, Name, _, _), FactCount),
     Row = _{
-        id: null,
+        id: SchemaId,
         builtin: true,
+        stored: false,
         namespace: Namespace,
         name: Name,
         arity: Arity,
@@ -728,9 +732,6 @@ ask_builtin_schema_row(Namespace, Name, Arity, KeyPositions, DecisionPosition, R
         factCount: FactCount
     }.
 
-% Keep in step with builtin_decision_predicate/5 in kb.pl.
-builtin_argument_names(permission_rule, [actor, action, resource, decision]).
-
 ask_schema_row(SchemaId, Namespace, Name, Arity, ArgumentNames, ArgumentTypes, Row) :-
     kb_entity(SchemaId, fact, Props),
     (   memberchk(key_arguments=KeysRaw, Props)
@@ -755,6 +756,7 @@ ask_schema_row(SchemaId, Namespace, Name, Arity, ArgumentNames, ArgumentTypes, R
     Row = _{
         id: SchemaId,
         builtin: false,
+        stored: true,
         namespace: Namespace,
         name: Name,
         arity: Arity,

package/src/kb.pl

@@ -61,6 +61,7 @@
     adr_chain/2,
     deprecated_no_successor/1,
     symbol_no_req_coverage/2,
+    changed_symbol_no_req_coverage/2,
     predicate_schema/6,
     predicate_schema_keys/4,
     predicate_fact/5,
@@ -2845,6 +2846,15 @@ bind_key_arguments([Position|Positions], ArgsA, ArgsB) :-
 % predicate-catalog-4.ts (permission_rule: actor, action, resource).
 builtin_decision_predicate(default, permission_rule, 4, [1, 2, 3], 4).
 
+%% builtin_predicate_signature(?Name, ?SchemaId, ?ArgumentNames)
+% implements REQ-kibi-query-fact-filters
+% The catalog id and argument names of a built-in decision predicate.  The
+% id is the one kb_model accepts as schemaId; no entity with that id is
+% stored, so a kb_query by id finds nothing.  Keep in step with
+% builtin_decision_predicate/5 and the catalog entry in
+% packages/cli/src/operations/modeling/predicate-catalog-4.ts.
+builtin_predicate_signature(permission_rule, 'FACT-SCHEMA-PERMISSION-RULE', [actor, action, resource, decision]).
+
 %% effective_decision(+Decision, +Polarity, -Effect)
 effective_decision(allow, assert, allow).
 effective_decision(allow, deny, deny).
@@ -3318,6 +3328,23 @@ changed_symbol_missing_req(Symbol, MinLinks, Count) :-
     length(UniqueReqs, Count),
     Count < MinLinks.
 
+%% changed_symbol_no_req_coverage(+ExtraSymbols, -Symbol)
+% The full-check symbol-coverage rule restricted to a staged change set: the
+% overlay changed_symbol/1 facts plus ExtraSymbols (symbols whose staged
+% manifest entry changed). It reuses symbol_no_req_coverage/2, so the staged
+% gate and `kibi check` judge coverage identically: a direct req->test edge
+% counts only while the requirement has no scenario.
+% implements REQ-014
+changed_symbol_no_req_coverage(ExtraSymbols, Symbol) :-
+    findall(Candidate,
+            (   changed_symbol(Candidate)
+            ;   member(Candidate, ExtraSymbols)
+            ),
+            Candidates0),
+    sort(Candidates0, Candidates),
+    member(Symbol, Candidates),
+    symbol_no_req_coverage(Symbol, _).
+
 %% changed_symbol_violation(+Symbol, +MinLinks, -Count, -File, -Line, -Col, -Name)
 % Full violation record for a changed symbol missing requirements.
 changed_symbol_violation(Symbol, MinLinks, Count, File, Line, Col, Name) :-

package/src/rule_registry.pl

@@ -17,6 +17,7 @@
 known_rule('must-priority-coverage').
 known_rule('symbol-coverage').
 known_rule('symbol-traceability').
+known_rule('symbol-granularity').
 known_rule('no-dangling-refs').
 known_rule('source-relationship-parity').
 known_rule('branch-store-not-compiled').
@@ -59,12 +60,17 @@ known_rule('adr-proposed').
 known_rule('predicate-schema-conformance').
 known_rule('entity-context-missing').
 known_rule('entity-context-acknowledged').
+known_rule('decision-firm-unreferenced').
+known_rule('decision-firm-superseded').
+known_rule('supersedes-reason-missing').
+known_rule('supersedes-reason-acknowledged').
 known_rule('policy-ownership').
 known_rule('policy-markers').
 
 rule_enforcement_class('must-priority-coverage', canonical).
 rule_enforcement_class('symbol-coverage', canonical).
 rule_enforcement_class('symbol-traceability', canonical).
+rule_enforcement_class('symbol-granularity', canonical).
 rule_enforcement_class('no-dangling-refs', canonical).
 rule_enforcement_class('source-relationship-parity', canonical).
 rule_enforcement_class('branch-store-not-compiled', canonical).
@@ -107,12 +113,17 @@ rule_enforcement_class('adr-proposed', advisory).
 rule_enforcement_class('predicate-schema-conformance', advisory).
 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('supersedes-reason-missing', canonical).
+rule_enforcement_class('supersedes-reason-acknowledged', advisory).
 rule_enforcement_class('policy-ownership', canonical).
 rule_enforcement_class('policy-markers', canonical).
 
 rule_implementation('must-priority-coverage', prolog).
 rule_implementation('symbol-coverage', prolog).
 rule_implementation('symbol-traceability', prolog).
+rule_implementation('symbol-granularity', typescript).
 rule_implementation('no-dangling-refs', prolog).
 rule_implementation('source-relationship-parity', typescript).
 rule_implementation('branch-store-not-compiled', typescript).
@@ -155,6 +166,10 @@ rule_implementation('adr-proposed', prolog).
 rule_implementation('predicate-schema-conformance', typescript).
 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('supersedes-reason-missing', typescript).
+rule_implementation('supersedes-reason-acknowledged', typescript).
 rule_implementation('policy-ownership', typescript).
 rule_implementation('policy-markers', typescript).
 
@@ -231,6 +246,7 @@ rule_predicate_arity('adr-proposed', 1).
 rule_description('must-priority-coverage', 'Every must-priority requirement must have a scenario and a test').
 rule_description('symbol-coverage', 'Production symbols need qualifying coverage via covered_by plus a canonical requirement/scenario test path').
 rule_description('symbol-traceability', 'Production symbols must directly implement requirements for ownership; covered_by is coverage only and executable_for is test identity only').
+rule_description('symbol-granularity', 'A symbol with traceability relationships must not link its source file coarsely while narrower behavioral symbols are available, unless it carries an allowed granularity_reason; the staged gate\'s symbol_granularity_violation evaluated KB-wide').
 rule_description('no-dangling-refs', 'All relationship targets must exist in the KB').
 rule_description('source-relationship-parity', 'Authored Markdown and relationship-shard edges must exactly match the compiled KB').
 rule_description('branch-store-not-compiled', 'The current branch\'s KB store must be compiled from the authored .kb/ sources; a missing or empty store is reported once, naming kibi sync, instead of every store-backed rule reading an empty KB').
@@ -273,5 +289,9 @@ rule_description('adr-proposed', 'Informational: an ADR that is still proposed a
 rule_description('predicate-schema-conformance', 'Predicate facts match a predicate_schema (project-local, or the built-in catalog in the default namespace) and use its declared argument constants').
 rule_description('entity-context-missing', 'A current requirement, scenario, test, ADR or observation/meta fact must carry body context: at least 12 words of prose (requirements: under a Context, Rationale, Why, Background, Source, Notes or Evidence heading) that do not restate the title or semantic_text; entities tagged review:context-missing are acknowledged legacy and exempt').
 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('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').
 rule_description('policy-markers', 'When a plugin activated for kibi.check-policy.v1 declares marker rules, every file implementing a requirement grounded in the rule\'s pattern predicate (with its declared sibling files) must contain each marker the KB declares for that pattern').