kibi-core 0.1.4

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "kibi-core",
+  "version": "0.1.4",
+  "private": false,
+  "description": "Core Prolog modules and RDF graph logic for Kibi",
+  "type": "module",
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.0"
+  },
+  "main": "./src/kb.pl",
+  "files": ["src/**/*.pl", "schema/**/*.pl"],
+  "license": "AGPL-3.0-or-later",
+  "author": "Piotr Franczyk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Looted/kibi.git"
+  }
+}

package/schema/entities.pl

@@ -0,0 +1,50 @@
+% Module: kibi_entities
+% Entity type and property definitions for Kibi knowledge base
+:- module(kibi_entities, [entity_type/1, entity_property/3, required_property/2, optional_property/2]).
+
+% Entity types
+entity_type(req).
+entity_type(scenario).
+entity_type(test).
+entity_type(adr).
+entity_type(flag).
+entity_type(event).
+entity_type(symbol).
+entity_type(fact).
+
+% entity_property(EntityType, Property, Type).
+% Basic typing hints (atom, string, datetime, list, uri)
+entity_property(_, id, atom).
+entity_property(_, title, string).
+entity_property(_, status, atom).
+entity_property(_, created_at, datetime).
+entity_property(_, updated_at, datetime).
+entity_property(_, source, uri).
+
+% Optional properties
+entity_property(_, tags, list).
+entity_property(_, owner, atom).
+entity_property(_, priority, atom).
+entity_property(_, severity, atom).
+entity_property(_, links, list).
+entity_property(_, text_ref, uri).
+
+% Required properties for all entity types
+required_property(Type, id) :- entity_type(Type).
+required_property(Type, title) :- entity_type(Type).
+required_property(Type, status) :- entity_type(Type).
+required_property(Type, created_at) :- entity_type(Type).
+required_property(Type, updated_at) :- entity_type(Type).
+required_property(Type, source) :- entity_type(Type).
+
+% Optional properties for all entity types
+optional_property(Type, tags) :- entity_type(Type).
+optional_property(Type, owner) :- entity_type(Type).
+optional_property(Type, priority) :- entity_type(Type).
+optional_property(Type, severity) :- entity_type(Type).
+optional_property(Type, links) :- entity_type(Type).
+optional_property(Type, text_ref) :- entity_type(Type).
+
+% Documentation helpers
+% list all entity types
+all_entity_types(Ts) :- findall(T, entity_type(T), Ts).

package/schema/relationships.pl

@@ -0,0 +1,47 @@
+% Module: kibi_relationships
+% Relationship type definitions and valid entity combinations
+:- module(kibi_relationships, [relationship_type/1, valid_relationship/3, relationship_metadata/1]).
+
+% Relationship types
+relationship_type(depends_on).
+relationship_type(specified_by).
+relationship_type(verified_by).
+relationship_type(validates).
+relationship_type(implements).
+relationship_type(covered_by).
+relationship_type(constrained_by).
+relationship_type(guards).
+relationship_type(publishes).
+relationship_type(consumes).
+relationship_type(relates_to).
+relationship_type(supersedes).
+relationship_type(constrains).
+relationship_type(requires_property).
+
+% valid_relationship(RelType, FromType, ToType).
+valid_relationship(depends_on, req, req).
+valid_relationship(specified_by, req, scenario).
+valid_relationship(verified_by, req, test).
+valid_relationship(validates, test, req).
+valid_relationship(implements, symbol, req).
+valid_relationship(covered_by, symbol, test).
+valid_relationship(constrained_by, symbol, adr).
+% guards can target symbol, event, or req
+valid_relationship(guards, flag, symbol).
+valid_relationship(guards, flag, event).
+valid_relationship(guards, flag, req).
+valid_relationship(publishes, symbol, event).
+valid_relationship(consumes, symbol, event).
+valid_relationship(constrains, req, fact).
+valid_relationship(requires_property, req, fact).
+
+%% supersedes(+NewAdrId, +OldAdrId)
+%% NewAdrId is the decision that replaces OldAdrId.
+%% OldAdrId's status should be archived or deprecated as a consequence.
+valid_relationship(supersedes, adr, adr).
+valid_relationship(supersedes, req, req).
+% escape hatch - allow any to any
+valid_relationship(relates_to, _, _).
+
+% Relationship metadata fields (some optional)
+relationship_metadata([created_at, created_by, source, confidence]).

package/schema/validation.pl

@@ -0,0 +1,49 @@
+% Module: kibi_validation
+% Validation rules for entities and relationships in Kibi
+:- module(kibi_validation,
+          [ validate_entity/2,        % +Type, +Props
+            validate_relationship/3,  % +RelType, +FromEntity, +ToEntity
+            validate_property_type/3  % +Type, +Prop, +Value
+          ]).
+
+:- use_module('entities.pl').
+:- use_module('relationships.pl').
+
+% validate_entity(+Type, +Props:list)
+% Props is a list of Property=Value pairs (e.g. id=ID, title=Title)
+validate_entity(Type, Props) :-
+    % check entity type exists
+    entity_type(Type),
+    % required properties present
+    forall(required_property(Type, P), memberchk(P=_Val, Props)),
+    % all properties have correct types
+    forall(member(Key=Val, Props), validate_property_type(Type, Key, Val)).
+
+% validate_relationship(+RelType, +From, +To)
+% From and To are pairs Type=Id or structures type(Type) - allow Type or Type=Id
+validate_relationship(RelType, From, To) :-
+    relationship_type(RelType),
+    % extract types
+    type_of(From, FromType),
+    type_of(To, ToType),
+    % valid combination
+    valid_relationship(RelType, FromType, ToType).
+
+type_of(Type, Type) :- atom(Type), entity_type(Type), !.
+type_of(Type=_Id, Type) :- atom(Type), entity_type(Type), !.
+
+% validate_property_type(+EntityType, +Prop, +Value)
+validate_property_type(_Type, Prop, Value) :-
+    % find declared property type, default to atom
+    ( entity_property(_Any, Prop, Kind) -> true ; Kind = atom ),
+    check_kind(Kind, Value), !.
+
+% check_kind(Kind, Value) succeeds if Value matches Kind
+check_kind(atom, V) :- atom(V).
+check_kind(string, V) :- string(V).
+check_kind(datetime, V) :- string(V). % accept ISO strings for now
+check_kind(list, V) :- is_list(V).
+check_kind(uri, V) :- string(V).
+
+% Fallback false
+check_kind(_, _) :- fail.

package/src/kb.pl

@@ -0,0 +1,616 @@
+% Module: kb
+% Core Knowledge Base module with RDF persistence and audit logging
+:- module(kb, [
+    kb_attach/1,
+    kb_detach/0,
+    kb_save/0,
+    with_kb_mutex/1,
+    kb_assert_entity/2,
+    kb_retract_entity/1,
+    kb_entity/3,
+    kb_entities_by_source/2,
+    kb_assert_relationship/4,
+    kb_relationship/3,
+    transitively_implements/2,
+    transitively_depends/2,
+    impacted_by_change/2,
+    affected_symbols/2,
+    coverage_gap/2,
+    untested_symbols/1,
+    stale/2,
+    orphaned/1,
+    conflicting/2,
+    deprecated_still_used/2,
+    current_adr/1,
+    superseded_by/2,
+    adr_chain/2,
+    deprecated_no_successor/1,
+    symbol_no_req_coverage/2,
+    contradicting_reqs/3,
+    normalize_term_atom/2,
+    changeset/4, % Export for testing
+    kb_uri/1
+]).
+
+:- use_module(library(semweb/rdf11)).
+:- use_module(library(persistency)).
+:- use_module(library(thread)).
+:- use_module(library(filesex)).
+:- use_module(library(ordsets)).
+:- use_module('../schema/entities.pl', [entity_type/1, entity_property/3, required_property/2]).
+:- use_module('../schema/relationships.pl', [relationship_type/1, valid_relationship/3]).
+:- use_module('../schema/validation.pl', [validate_entity/2, validate_relationship/3]).
+
+% Constants
+kb_uri('urn-kibi:').
+
+% RDF namespace for KB entities and relationships
+:- kb_uri(URI), rdf_register_prefix(kb, URI).
+:- rdf_register_prefix(xsd, 'http://www.w3.org/2001/XMLSchema#').
+:- rdf_meta
+    kb_entity(?, ?, ?),
+    kb_relationship(?, ?, ?).
+
+% Persistent audit log declaration
+:- persistent
+    changeset(timestamp:atom, operation:atom, entity_id:atom, data:any).
+
+% Dynamic facts to track KB state
+:- dynamic kb_attached/1.
+:- dynamic kb_audit_db/1.
+:- dynamic kb_graph/1.
+
+%% kb_attach(+Directory)
+% Attach to a KB directory with RDF persistence and file locking.
+% Creates directory if it doesn't exist.
+kb_attach(Directory) :-
+    % If we were already attached in this process, detach first.
+    % This prevents accidentally loading the same RDF snapshot multiple times.
+    (   kb_attached(_)
+    ->  kb_detach
+    ;   true
+    ),
+    % Ensure directory exists
+    (   exists_directory(Directory)
+    ->  true
+    ;   make_directory_path(Directory)
+    ),
+    % Create RDF graph name from directory
+    atom_concat('file://', Directory, GraphURI),
+    % If a graph with this URI is already present, unload it to avoid duplicates.
+    (   rdf_graph(GraphURI)
+    ->  rdf_unload_graph(GraphURI)
+    ;   true
+    ),
+    % Load existing RDF data if present
+    atom_concat(Directory, '/kb.rdf', DataFile),
+    (   exists_file(DataFile)
+    ->  rdf_load(DataFile, [graph(GraphURI), silent(true)])
+    ;   true
+    ),
+    % Set up audit log - only attach if not already attached
+    atom_concat(Directory, '/audit.log', AuditLog),
+    (   db_attached(AuditLog)
+    ->  true  % Already attached
+    ;   db_attach(AuditLog, [])
+    ),
+    % Track attachment state
+    assert(kb_attached(Directory)),
+    assert(kb_audit_db(AuditLog)),
+    assert(kb_graph(GraphURI)).
+
+%% kb_detach
+% Safely detach from KB, flushing journals and closing audit log.
+kb_detach :-
+    (   kb_attached(_Directory)
+    ->  (
+            kb_save,
+            % Clear state
+            retractall(kb_attached(_)),
+            retractall(kb_audit_db(_)),
+            retractall(kb_graph(_))
+        )
+    ;   true
+    ).
+
+%% kb_save
+% Save RDF graph and sync audit log to disk
+kb_save :-
+    (   kb_attached(Directory)
+    ->  (
+            % Save RDF graph to file with namespace declarations
+            atom_concat(Directory, '/kb.rdf', DataFile),
+            % Get current graph URI
+            kb_graph(GraphURI),
+            % If we have a graph URI, save that graph. Otherwise save all data
+            % (fallback) so a kb.rdf is always produced. Report errors if save fails.
+            (   kb_graph(GraphURI)
+            ->  catch(rdf_save(DataFile, [graph(GraphURI), base_uri('urn-kibi:'), namespaces([kb, xsd])]), E, print_message(error, E))
+            ;   catch(rdf_save(DataFile, [base_uri('urn-kibi:'), namespaces([kb, xsd])]), E2, print_message(error, E2))
+            ),
+            % Sync audit log
+            (   kb_audit_db(AuditLog)
+            ->  db_sync(AuditLog)
+            ;   true
+            )
+        )
+    ;   true
+    ).
+
+%% with_kb_mutex(+Goal)
+% Execute Goal with KB mutex protection for thread safety.
+with_kb_mutex(Goal) :-
+    with_mutex(kb_lock, Goal).
+
+%% kb_assert_entity(+Type, +Properties)
+% Assert an entity into the KB with validation and audit logging.
+% Properties is a list of Key=Value pairs.
+kb_assert_entity(Type, Props) :-
+    % Validate entity
+    validate_entity(Type, Props),
+    % Extract ID
+    memberchk(id=Id, Props),
+    % Get current graph
+    kb_graph(Graph),
+    % Execute with mutex protection
+    with_kb_mutex((
+        % Create entity URI using prefix notation for namespace expansion
+        format(atom(EntityURI), 'kb:entity/~w', [Id]),
+        % Upsert semantics: remove any existing triples for this entity first.
+        rdf_retractall(EntityURI, _, _, Graph),
+        % Store type as string literal to prevent URI interpretation
+        atom_string(Type, TypeStr),
+        rdf_assert(EntityURI, kb:type, TypeStr^^'http://www.w3.org/2001/XMLSchema#string', Graph),
+        % Store all properties
+        forall(
+            member(Key=Value, Props),
+            store_property(EntityURI, Key, Value, Graph)
+        ),
+        % Log to audit
+        get_time(Timestamp),
+        format_time(atom(TS), '%FT%T%:z', Timestamp),
+        assert_changeset(TS, upsert, Id, Type-Props)
+    )).
+
+%% kb_retract_entity(+Id)
+% Remove an entity from the KB with audit logging.
+kb_retract_entity(Id) :-
+    kb_graph(Graph),
+    with_kb_mutex((
+        % Create entity URI
+        atom_concat('kb:entity/', Id, EntityURI),
+        % Remove all triples for this entity
+        rdf_retractall(EntityURI, _, _, Graph),
+        % Log to audit
+        get_time(Timestamp),
+        format_time(atom(TS), '%FT%T%:z', Timestamp),
+        assert_changeset(TS, delete, Id, null)
+    )).
+
+%% kb_entity(?Id, ?Type, ?Properties)
+% Query entities from the KB.
+% Properties is unified with a list of Key=Value pairs.
+kb_entity(Id, Type, Props) :-
+    kb_graph(Graph),
+    % Find entity by pattern - use unquoted namespace term kb:type
+    (   var(Id)
+    ->  rdf(EntityURI, kb:type, TypeLiteral, Graph),
+        atom_concat('kb:entity/', Id, EntityURI)
+    ;   atom_concat('kb:entity/', Id, EntityURI),
+        rdf(EntityURI, kb:type, TypeLiteral, Graph)
+    ),
+    % Extract type - convert string literal to atom
+    literal_to_atom(TypeLiteral, Type),
+    % Collect all properties (exclude kb:type which expands to full URI)
+    findall(Key=Value, (
+        rdf(EntityURI, PropURI, ValueLiteral, Graph),
+        kb_uri(BaseURI),
+        atom_concat(BaseURI, type, TypeURI),
+        PropURI \= TypeURI,
+        uri_to_key(PropURI, Key),
+        literal_to_value(ValueLiteral, Value)
+    ), Props).
+
+%% kb_entities_by_source(+SourcePath, -Ids)
+% Returns all entity IDs whose source property matches SourcePath (substring match).
+kb_entities_by_source(SourcePath, Ids) :-
+    findall(Id,
+        (kb_entity(Id, _Type, Props),
+         memberchk(source-S, Props),
+         sub_atom(S, _, _, _, SourcePath)),
+        Ids).
+
+%% kb_assert_relationship(+Type, +From, +To, +Metadata)
+% Assert a relationship between two entities with validation.
+kb_assert_relationship(RelType, FromId, ToId, _Metadata) :-
+    kb_graph(Graph),
+    % Validate entities exist and relationship is valid
+    % Use once/1 to keep this predicate deterministic even if the store
+    % contains duplicate type triples from previous versions.
+    once(kb_entity(FromId, FromType, _)),
+    once(kb_entity(ToId, ToType, _)),
+    validate_relationship(RelType, FromType, ToType),
+    % Execute with mutex protection
+    with_kb_mutex((
+        % Create entity URIs
+        atom_concat('kb:entity/', FromId, FromURI),
+        atom_concat('kb:entity/', ToId, ToURI),
+        % Create relationship property URI (full URI to match saved/loaded RDF)
+        kb_uri(BaseURI),
+        atom_concat(BaseURI, RelType, RelURI),
+        % Upsert semantics: ensure the exact triple isn't duplicated.
+        rdf_retractall(FromURI, RelURI, ToURI, Graph),
+        % Assert relationship triple
+        rdf_assert(FromURI, RelURI, ToURI, Graph),
+        % Log to audit
+        get_time(Timestamp),
+        format_time(atom(TS), '%FT%T%:z', Timestamp),
+        format(atom(RelId), '~w->~w', [FromId, ToId]),
+        assert_changeset(TS, upsert_rel, RelId, RelType-[from=FromId, to=ToId])
+    )).
+
+%% kb_relationship(?Type, ?From, ?To)
+% Query relationships from the KB.
+kb_relationship(RelType, FromId, ToId) :-
+    kb_graph(Graph),
+    % Create relationship property URI (full URI to match loaded RDF)
+    kb_uri(BaseURI),
+    atom_concat(BaseURI, RelType, RelURI),
+    % Find matching relationships
+    rdf(FromURI, RelURI, ToURI, Graph),
+    % Extract IDs from URIs
+    atom_concat('kb:entity/', FromId, FromURI),
+    atom_concat('kb:entity/', ToId, ToURI).
+
+% Helper predicates
+
+%% store_property(+EntityURI, +Key, +Value, +Graph)
+% Store a property as an RDF triple with appropriate datatype.
+% All values are stored as typed string literals to avoid URI interpretation issues.
+% Uses prefix notation (kb:Key) to enable proper namespace expansion.
+store_property(EntityURI, Key, Value, Graph) :-
+    % Build property URI using prefix notation for namespace expansion
+    format(atom(PropURI), 'kb:~w', [Key]),
+    % Always convert to literal (never store as URI/resource)
+    value_to_literal(Value, Literal),
+    rdf_assert(EntityURI, PropURI, Literal, Graph).
+
+%% value_to_literal(+Value, -Literal)
+% Convert Prolog value to RDF literal with appropriate datatype.
+value_to_literal(Value, Literal) :-
+    (   string(Value)
+    ->  Literal = Value^^'http://www.w3.org/2001/XMLSchema#string'
+    ;   is_list(Value)
+    ->  format(atom(ListStr), '~w', [Value]),
+        Literal = ListStr^^'http://www.w3.org/2001/XMLSchema#string'
+    ;   format(atom(Str), '~w', [Value]),
+        Literal = Str^^'http://www.w3.org/2001/XMLSchema#string'
+    ).
+
+%% literal_to_value(+Literal, -Value)
+% Extract value from RDF literal, parse list syntax back to Prolog lists.
+literal_to_value(Literal, Value) :-
+    (   % Handle ^^/2 functor (RDF typed literal shorthand)
+        Literal = ^^(StrVal, 'http://www.w3.org/2001/XMLSchema#string')
+    ->  (   % Preserve RDF typed literal functor for string values so callers
+            % can inspect datatype if needed; but also attempt to parse lists
+            % encoded as string into Prolog lists when appropriate.
+            (atom(StrVal) ; string(StrVal)),
+            (atom_concat('[', _, StrVal) ; string_concat("[", _, StrVal)),
+            catch(atom_to_term(StrVal, ParsedValue, []), _, fail),
+            is_list(ParsedValue)
+        ->  Value = ParsedValue
+        ;   Value = ^^(StrVal, 'http://www.w3.org/2001/XMLSchema#string')
+        )
+    ;   Literal = ^^(Val, Type)
+    ->  Value = ^^(Val, Type)  % Preserve other typed literals as their functor
+    ;   Literal = literal(type('http://www.w3.org/2001/XMLSchema#string', StrVal))
+    ->  (   % Try to parse as Prolog list term (handles both atoms and strings)
+            (atom(StrVal) ; string(StrVal)),
+            (atom_concat('[', _, StrVal) ; string_concat("[", _, StrVal)),
+            catch(atom_to_term(StrVal, ParsedValue, []), _, fail),
+            is_list(ParsedValue)
+        ->  Value = ParsedValue
+        ;   Value = StrVal
+        )
+    ;   Literal = literal(type(_, _))
+    ->  Value = Literal  % Keep other typed literals as-is
+    ;   Literal = literal(lang(_, Val))
+    ->  Value = Val
+    ;   Literal = literal(Value)
+    ->  true
+    ;   Value = Literal
+    ).
+
+%% literal_to_atom(+Literal, -Atom)
+% Convert RDF literal to atom (for type field).
+literal_to_atom(Literal, Atom) :-
+    (   % Handle RDF typed literal shorthand functor ^^(Value, Type)
+        Literal = ^^(Val, _Type)
+    ->  (   % Val may be atom or string
+            atom(Val)
+        ->  Atom = Val
+        ;   atom_string(Atom, Val)
+        )
+    ;   Literal = literal(type(_, StringVal))
+    ->  atom_string(Atom, StringVal)
+    ;   Literal = literal(Value)
+    ->  (atom(Value) -> Atom = Value ; atom_string(Atom, Value))
+    ;   atom(Literal)
+    ->  Atom = Literal
+    ;   atom_string(Atom, Literal)
+    ).
+
+%% uri_to_key(+URI, -Key)
+% Convert URI to property key (strip kb: namespace prefix).
+uri_to_key(URI, Key) :-
+    (   kb_uri(BaseURI),
+        atom_concat(BaseURI, Key, URI)
+    ->  true
+    ;   atom_concat('kb:', Key, URI)
+    ->  true
+    ;   URI = Key
+    ).
+
+%% ------------------------------------------------------------------
+%% Inference predicates (Phase 1)
+%% ------------------------------------------------------------------
+
+%% transitively_implements(+Symbol, +Req)
+% A symbol transitively implements a requirement if it directly implements it,
+% or if it is covered by a test that validates/verifies the requirement.
+transitively_implements(Symbol, Req) :-
+    kb_relationship(implements, Symbol, Req).
+transitively_implements(Symbol, Req) :-
+    kb_relationship(covered_by, Symbol, Test),
+    kb_relationship(validates, Test, Req).
+transitively_implements(Symbol, Req) :-
+    kb_relationship(covered_by, Symbol, Test),
+    kb_relationship(verified_by, Req, Test).
+
+%% transitively_depends(+Req1, +Req2)
+% Req1 transitively depends on Req2 through depends_on chains.
+transitively_depends(Req1, Req2) :-
+    transitively_depends_(Req1, Req2, []).
+
+transitively_depends_(Req1, Req2, _) :-
+    kb_relationship(depends_on, Req1, Req2).
+transitively_depends_(Req1, Req2, Visited) :-
+    kb_relationship(depends_on, Req1, Mid),
+    Req1 \= Mid,
+    \+ memberchk(Mid, Visited),
+    transitively_depends_(Mid, Req2, [Req1|Visited]).
+
+%% impacted_by_change(?Entity, +Changed)
+% Entity is impacted if it is connected to Changed by any relationship
+% direction via bounded, cycle-safe traversal.
+impacted_by_change(Changed, Changed).
+impacted_by_change(Entity, Changed) :-
+    dif(Entity, Changed),
+    connected_entity(Changed, Entity, [Changed]).
+
+connected_entity(Current, Target, _Visited) :-
+    linked_entity(Current, Target).
+connected_entity(Current, Target, Visited) :-
+    linked_entity(Current, Next),
+    \+ memberchk(Next, Visited),
+    connected_entity(Next, Target, [Next|Visited]).
+
+linked_entity(A, B) :-
+    relationship_type(RelType),
+    kb_relationship(RelType, A, B).
+linked_entity(A, B) :-
+    relationship_type(RelType),
+    kb_relationship(RelType, B, A).
+
+%% affected_symbols(+Req, -Symbols)
+% Symbols affected by a requirement change include symbols implementing Req,
+% and symbols implementing requirements that depend on Req.
+affected_symbols(Req, Symbols) :-
+    setof(Symbol,
+          RelatedReq^(requirement_in_scope(RelatedReq, Req),
+                     transitively_implements(Symbol, RelatedReq)),
+          Symbols),
+    !.
+affected_symbols(_, []).
+
+requirement_in_scope(Req, Req).
+requirement_in_scope(RelatedReq, Req) :-
+    transitively_depends(RelatedReq, Req).
+
+%% coverage_gap(+Req, -Reason)
+% Detects missing scenario/test coverage for MUST requirements.
+coverage_gap(Req, missing_scenario_and_test) :-
+    must_requirement(Req),
+    \+ has_scenario(Req),
+    \+ has_test(Req).
+coverage_gap(Req, missing_scenario) :-
+    must_requirement(Req),
+    \+ has_scenario(Req),
+    has_test(Req).
+coverage_gap(Req, missing_test) :-
+    must_requirement(Req),
+    has_scenario(Req),
+    \+ has_test(Req).
+
+must_requirement(Req) :-
+    kb_entity(Req, req, Props),
+    memberchk(priority=Priority, Props),
+    normalize_term_atom(Priority, PriorityAtom),
+    atom_string(PriorityAtom, PriorityStr),
+    sub_string(PriorityStr, _, 4, 0, "must").
+
+has_scenario(Req) :-
+    once(kb_relationship(specified_by, Req, _)).
+
+has_test(Req) :-
+    once(kb_relationship(validates, _, Req)).
+has_test(Req) :-
+    once(kb_relationship(verified_by, Req, _)).
+
+%% untested_symbols(-Symbols)
+% Returns symbols with no test coverage relationship.
+untested_symbols(Symbols) :-
+    setof(Symbol,
+          (kb_entity(Symbol, symbol, _),
+           \+ kb_relationship(covered_by, Symbol, _)),
+          Symbols),
+    !.
+untested_symbols([]).
+
+%% stale(+Entity, +MaxAgeDays)
+% Entity is stale if updated_at is older than MaxAgeDays.
+stale(Entity, MaxAgeDays) :-
+    number(MaxAgeDays),
+    MaxAgeDays >= 0,
+    kb_entity(Entity, _, Props),
+    memberchk(updated_at=UpdatedAt, Props),
+    coerce_timestamp_atom(UpdatedAt, UpdatedAtAtom),
+    parse_time(UpdatedAtAtom, iso_8601, UpdatedTs),
+    get_time(NowTs),
+    AgeDays is (NowTs - UpdatedTs) / 86400,
+    AgeDays > MaxAgeDays.
+
+%% orphaned(+Symbol)
+% Symbol is orphaned if it has no core traceability links.
+orphaned(Symbol) :-
+    kb_entity(Symbol, symbol, _),
+    \+ kb_relationship(implements, Symbol, _),
+    \+ kb_relationship(covered_by, Symbol, _),
+    \+ kb_relationship(constrained_by, Symbol, _).
+
+%% conflicting(?Adr1, ?Adr2)
+% ADRs conflict if they both constrain the same symbol and are distinct.
+conflicting(Adr1, Adr2) :-
+    kb_relationship(constrained_by, Symbol, Adr1),
+    kb_relationship(constrained_by, Symbol, Adr2),
+    Adr1 \= Adr2,
+    Adr1 @< Adr2.
+
+%% deprecated_still_used(+Adr, -Symbols)
+% Deprecated/archived/rejected ADRs that still constrain symbols.
+deprecated_still_used(Adr, Symbols) :-
+    kb_entity(Adr, adr, Props),
+    memberchk(status=Status, Props),
+    normalize_term_atom(Status, StatusAtom),
+    memberchk(StatusAtom, [deprecated, archived, rejected]),
+    setof(Symbol, kb_relationship(constrained_by, Symbol, Adr), Symbols),
+    !.
+deprecated_still_used(_, []).
+
+%% ------------------------------------------------------------------
+%% ADR Supersession Predicates
+%% ------------------------------------------------------------------
+
+%% current_adr(+Id)
+% True when Id is an ADR not superseded by any other ADR.
+current_adr(Id) :-
+    kb_entity(Id, adr, _),
+    \+ kb_relationship(supersedes, _, Id).
+
+%% superseded_by(+OldId, -NewId)
+% Direct supersession.
+superseded_by(OldId, NewId) :-
+    kb_relationship(supersedes, NewId, OldId).
+
+%% adr_chain(+AnyId, -Chain)
+% Full ordered chain from AnyId to the current ADR (newest last).
+% Cycle-safe via visited accumulator.
+adr_chain(Id, Chain) :-
+    adr_chain_acc(Id, [], Chain).
+adr_chain_acc(Id, Visited, [Id]) :-
+    \+ member(Id, Visited),
+    \+ kb_relationship(supersedes, _, Id).
+adr_chain_acc(Id, Visited, [Id|Rest]) :-
+    \+ member(Id, Visited),
+    kb_relationship(supersedes, Newer, Id),
+    adr_chain_acc(Newer, [Id|Visited], Rest).
+
+%% deprecated_no_successor(+OldId)
+% Lint rule: ADR is archived/deprecated but has no supersedes relationship pointing to it.
+deprecated_no_successor(Id) :-
+    kb_entity(Id, adr, Props),
+    memberchk(status=Status, Props),
+    normalize_term_atom(Status, StatusAtom),
+    memberchk(StatusAtom, [archived, deprecated]),
+    \+ kb_relationship(supersedes, _, Id).
+
+%% current_req(+Id)
+% Requirement is current when active and not superseded by another requirement.
+current_req(Id) :-
+    kb_entity(Id, req, Props),
+    memberchk(status=Status, Props),
+    normalize_term_atom(Status, active),
+    \+ kb_relationship(supersedes, _, Id).
+
+%% contradicting_reqs(-ReqA, -ReqB, -Reason)
+% Two current requirements contradict if they constrain the same fact
+% but require different properties.
+contradicting_reqs(ReqA, ReqB, Reason) :-
+    current_req(ReqA),
+    current_req(ReqB),
+    ReqA @< ReqB,
+    kb_relationship(constrains, ReqA, FactId),
+    kb_relationship(constrains, ReqB, FactId),
+    kb_relationship(requires_property, ReqA, PropA),
+    kb_relationship(requires_property, ReqB, PropB),
+    PropA \= PropB,
+    format(atom(Reason), 'Conflict on ~w: ~w vs ~w', [FactId, PropA, PropB]).
+
+normalize_term_atom(Val^^_Type, Atom) :-
+    !,
+    normalize_term_atom(Val, Atom).
+normalize_term_atom(literal(type(_, Val)), Atom) :-
+    !,
+    normalize_term_atom(Val, Atom).
+normalize_term_atom(Val, Atom) :-
+    string(Val),
+    !,
+    atom_string(ValAtom, Val),
+    normalize_uri_atom(ValAtom, Atom).
+normalize_term_atom(Val, Atom) :-
+    atom(Val),
+    !,
+    normalize_uri_atom(Val, Atom).
+normalize_term_atom(Val, Atom) :-
+    term_string(Val, ValStr),
+    atom_string(ValAtom, ValStr),
+    normalize_uri_atom(ValAtom, Atom).
+
+normalize_uri_atom(Value, Atom) :-
+    (   sub_atom(Value, _, _, _, '/')
+    ->  atomic_list_concat(Parts, '/', Value),
+        last(Parts, Last),
+        Atom = Last
+    ;   Atom = Value
+    ).
+
+%% symbol_no_req_coverage(+Symbol, -Reason)
+% Find symbols that are not traceable to any functional requirement.
+symbol_no_req_coverage(Symbol, no_path_to_req) :-
+    kb_entity(Symbol, symbol, _),
+    \+ transitively_implements(Symbol, _).
+
+% Helper predicate for readability - symbols with no traceability
+symbol_uncovered(Symbol) :-
+    kb_entity(Symbol, symbol, _),
+    \+ transitively_implements(Symbol, _).
+
+
+coerce_timestamp_atom(Val^^_Type, Atom) :-
+    !,
+    coerce_timestamp_atom(Val, Atom).
+coerce_timestamp_atom(literal(type(_, Val)), Atom) :-
+    !,
+    coerce_timestamp_atom(Val, Atom).
+coerce_timestamp_atom(Val, Atom) :-
+    atom(Val),
+    !,
+    Atom = Val.
+coerce_timestamp_atom(Val, Atom) :-
+    string(Val),
+    !,
+    atom_string(Atom, Val).
+coerce_timestamp_atom(Val, Atom) :-
+    term_string(Val, Str),
+    atom_string(Atom, Str).