kibi-core 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-core",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "private": false,
   "description": "Core Prolog modules and RDF graph logic for Kibi",
   "type": "module",
@@ -8,7 +8,10 @@
     "node": ">=18"
   },
   "main": "./src/kb.pl",
-  "files": ["src/**/*.pl", "schema/**/*.pl"],
+  "files": [
+    "src/**/*.pl",
+    "schema/**/*.pl"
+  ],
   "license": "AGPL-3.0-or-later",
   "author": "Piotr Franczyk",
   "repository": {

package/schema/entities.pl

@@ -3,6 +3,7 @@
 :- module(kibi_entities, [entity_type/1, entity_property/3, required_property/2, optional_property/2]).
 
 % Entity types
+% implements REQ-004
 entity_type(req).
 entity_type(scenario).
 entity_type(test).
@@ -87,6 +88,7 @@ entity_property(symbol, sourceEndColumn, integer).
 % Typed test verification fields - only valid for test entities
 entity_property(test, verification_scope, atom).
 entity_property(test, verification_perspective, atom).
+entity_property(test, verification_contract, list_or_json).
 entity_property(test, verification_receipts, string).
 
 % Required properties for all entity types
@@ -113,6 +115,7 @@ optional_property(req, semantic_source_hash).
 optional_property(req, semantic_inventory).
 optional_property(test, verification_scope).
 optional_property(test, verification_perspective).
+optional_property(test, verification_contract).
 optional_property(test, verification_receipts).
 
 % Documentation helpers

package/schema/relationships.pl

@@ -3,6 +3,7 @@
 :- module(kibi_relationships, [relationship_type/1, valid_relationship/3, relationship_metadata/1]).
 
 % Relationship types
+% implements REQ-005
 relationship_type(depends_on).
 relationship_type(executable_for).
 relationship_type(specified_by).

package/schema/validation.pl

@@ -119,6 +119,7 @@ is_fact_only_field(claim_span_end).
 % is_test_only_field(+Key) - true if Key is a test-specific field
 is_test_only_field(verification_scope).
 is_test_only_field(verification_perspective).
+is_test_only_field(verification_contract).
 is_test_only_field(verification_receipts).
 
 % validate_fact_shape(+Kind, +Props)

package/src/checks.pl

@@ -6,6 +6,7 @@
 :- module(checks, [
     check_all/1,                    % Returns all violations as a dict
     check_all_json/1,               % Returns all violations as JSON string
+    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_symbol_traceability/2,    % Returns list of symbols lacking requirement traceability (ReqAdr option)
@@ -14,6 +15,7 @@
     check_required_fields/1,        % Returns list of missing required field violations
     check_deprecated_adrs/1,        % Returns list of deprecated ADR violations
     check_domain_contradictions/1,  % Returns list of contradiction violations
+    check_domain_contradictions_and_witnesses/2,
     check_domain_contradiction_witnesses/1,
     check_strict_fact_shape/1,      % Returns list of malformed strict fact violations
     check_strict_req_fact_pairing/1,% Returns list of malformed strict req/fact pairing violations
@@ -591,6 +593,15 @@ check_domain_contradictions(Violations) :-
     check_domain_contradiction_witnesses(Witnesses),
     maplist(contradiction_witness_violation, Witnesses, Violations).
 
+%% check_domain_contradictions_and_witnesses(-Violations, -Witnesses)
+% Compute the contradiction witness graph once when a caller needs both the
+% report violations and their exact evidence. The existing one-result
+% predicates remain unchanged; this paired form avoids duplicate work in
+% proof contexts without weakening any contradiction checks.
+check_domain_contradictions_and_witnesses(Violations, Witnesses) :-
+    check_domain_contradiction_witnesses(Witnesses),
+    maplist(contradiction_witness_violation, Witnesses, Violations).
+
 %% check_domain_contradiction_witnesses(-Witnesses)
 % Exact, JSON-safe evidence for every strict-property, ground-predicate, and
 % safe-rule contradiction result.  Rule overlap that cannot be proven or
@@ -989,9 +1000,11 @@ predicate_verifiability_kind_label(Kind, Label) :-
 
 %% check_logic_coverage(-Violations)
 % Validates explicitly declared atomic requirement claim manifests. Legacy
-% requirements without logic_claims remain eligible for gradual backfill; once
-% a manifest exists, every key must be grounded by a linked strict-property or
-% predicate fact carrying the same claim_key.
+% requirements without logic_claims remain eligible for gradual backfill. A
+% modeled proposition must be grounded exactly once; ambiguous, ontology-gap,
+% and missing propositions remain explicit unresolved inventory states and are
+% not required to have a ground fact (missing is reported by semantic
+% completeness).
 check_logic_coverage(Violations) :-
     findall(Violation, logic_coverage_violation(Violation), Violations0),
     sort(Violations0, Violations).
@@ -1006,6 +1019,7 @@ logic_coverage_violation(violation(
     kb:current_req(ReqId),
     requirement_logic_claims(ReqId, ClaimKeys),
     member(ClaimKey, ClaimKeys),
+    claim_requires_grounding(ReqId, ClaimKey),
     \+ grounded_requirement_claim(ReqId, ClaimKey),
     format(
         string(Description),
@@ -1014,6 +1028,24 @@ logic_coverage_violation(violation(
     ),
     violation_source(ReqId, req, Source).
 
+logic_coverage_violation(violation(
+    'logic-coverage',
+    ReqId,
+    Description,
+    "Keep ontology gaps, ambiguities, and missing interpretations unresolved; only modeled propositions may have logical ground facts",
+    Source
+)) :-
+    kb:current_req(ReqId),
+    requirement_inventory_status(ReqId, ClaimKey, Status),
+    memberchk(Status, [ambiguous, ontology_gap, missing]),
+    grounded_requirement_claim(ReqId, ClaimKey),
+    format(
+        string(Description),
+        "Requirement grounds unresolved ~w proposition ~w",
+        [Status, ClaimKey]
+    ),
+    violation_source(ReqId, req, Source).
+
 logic_coverage_violation(violation(
     'logic-coverage',
     ReqId,
@@ -1076,6 +1108,28 @@ requirement_logic_claims(ReqId, ClaimKeys) :-
     memberchk(logic_claims=RawClaimKeys, Props),
     kb:normalize_term_atom_list(RawClaimKeys, ClaimKeys).
 
+claim_requires_grounding(ReqId, ClaimKey) :-
+    requirement_inventory_status(ReqId, ClaimKey, modeled),
+    !.
+claim_requires_grounding(ReqId, ClaimKey) :-
+    \+ requirement_inventory_status(ReqId, ClaimKey, _).
+
+requirement_inventory_status(ReqId, ClaimKey, Status) :-
+    kb_entity(ReqId, req, Props),
+    memberchk(semantic_inventory=RawInventory, Props),
+    inventory_entries(RawInventory, Entries),
+    member(Entry, Entries),
+    checks_inventory_entry_field(Entry, claim_key, RawClaimKey),
+    kb:normalize_term_atom(RawClaimKey, ClaimKey),
+    inventory_entry_status(Entry, Status).
+
+checks_inventory_entry_field(Entry, Key, Value) :-
+    is_dict(Entry),
+    get_dict(Key, Entry, Value).
+checks_inventory_entry_field(Entry, Key, Value) :-
+    is_list(Entry),
+    memberchk(Key=Value, Entry).
+
 grounded_requirement_claim(ReqId, ClaimKey) :-
     grounded_requirement_claim_fact(ReqId, ClaimKey, _FactId).
 
@@ -1222,13 +1276,15 @@ rule_verifiability_description(Props, FactId, Description) :-
 rule_verifiability_description(Props, FactId, Description) :-
     memberchk(fact_kind=RawKind, Props),
     normalize_term_atom(RawKind, rule),
-    memberchk(rule_schema_id=SchemaId, Props),
+    memberchk(rule_schema_id=RawSchemaId, Props),
+    normalize_term_atom(RawSchemaId, SchemaId),
     \+ kb_entity(SchemaId, fact, _),
     format(string(Description), "Rule fact ~w references missing rule schema ~w", [FactId, SchemaId]).
 rule_verifiability_description(Props, FactId, Description) :-
     memberchk(fact_kind=RawKind, Props),
     normalize_term_atom(RawKind, rule),
-    memberchk(rule_schema_id=SchemaId, Props),
+    memberchk(rule_schema_id=RawSchemaId, Props),
+    normalize_term_atom(RawSchemaId, SchemaId),
     kb_entity(SchemaId, fact, SchemaProps),
     \+ valid_rule_schema_props(SchemaProps),
     format(string(Description), "Rule fact ~w references ~w, which is not a rule_schema fact", [FactId, SchemaId]).
@@ -1286,6 +1342,10 @@ inventory_entries(Raw, Entries) :-
         catch(atom_json_dict(Raw, JsonEntries, [value_string_as(string)]), _, fail),
         is_list(JsonEntries)
     ->  Entries = JsonEntries
+    ;   (atom(Raw) ; string(Raw)),
+        catch(term_string(PrologEntries, Raw), _, fail),
+        is_list(PrologEntries)
+    ->  Entries = PrologEntries
     ;   Entries = []
     ).
 
@@ -1341,6 +1401,64 @@ check_all_json(JsonString) :-
         JsonString
     ).
 
+%% check_selected_json(+Rules, -JsonString)
+% Run only the named aggregated checks. This is intentionally separate from
+% check_all/1 so focused diagnostics cannot evaluate unrelated rule queries.
+check_selected_json(Rules, JsonString) :-
+    check_selected(Rules, ViolationsDict),
+    violations_dict_to_json(ViolationsDict, JsonDict),
+    with_output_to_string(
+        json_write_dict(current_output, JsonDict, [width(0)]),
+        JsonString
+    ).
+
+check_selected(Rules, _{
+    must_priority_coverage: MustPriority,
+    symbol_coverage: SymbolCoverage,
+    symbol_traceability: SymbolTraceability,
+    no_dangling_refs: DanglingRefs,
+    no_cycles: Cycles,
+    required_fields: RequiredFields,
+    deprecated_adr_no_successor: DeprecatedADRs,
+    domain_contradictions: Contradictions,
+    strict_fact_shape: StrictFactShape,
+    strict_req_fact_pairing: StrictReqFactPairing,
+    strict_readiness: StrictReadiness,
+    predicate_verifiability: PredicateVerifiability,
+    logic_coverage: LogicCoverage,
+    rule_safety: RuleSafety,
+    rule_verifiability: RuleVerifiability,
+    semantic_completeness: SemanticCompleteness
+}) :-
+    selected_rule(Rules, 'must-priority-coverage', check_must_priority_coverage, MustPriority),
+    selected_rule(Rules, 'symbol-coverage', check_symbol_coverage, SymbolCoverage),
+    selected_rule_with_options(Rules, 'symbol-traceability', check_symbol_traceability, SymbolTraceability),
+    selected_rule(Rules, 'no-dangling-refs', check_no_dangling_refs, DanglingRefs),
+    selected_rule(Rules, 'no-cycles', check_no_cycles, Cycles),
+    selected_rule(Rules, 'required-fields', check_required_fields, RequiredFields),
+    selected_rule(Rules, 'deprecated-adr-no-successor', check_deprecated_adrs, DeprecatedADRs),
+    selected_rule(Rules, 'domain-contradictions', check_domain_contradictions, Contradictions),
+    selected_rule(Rules, 'strict-fact-shape', check_strict_fact_shape, StrictFactShape),
+    selected_rule(Rules, 'strict-req-fact-pairing', check_strict_req_fact_pairing, StrictReqFactPairing),
+    selected_rule(Rules, 'strict-readiness', check_strict_readiness, StrictReadiness),
+    selected_rule(Rules, 'predicate-verifiability', check_predicate_verifiability, PredicateVerifiability),
+    selected_rule(Rules, 'logic-coverage', check_logic_coverage, LogicCoverage),
+    selected_rule(Rules, 'rule-safety', check_rule_safety, RuleSafety),
+    selected_rule(Rules, 'rule-verifiability', check_rule_verifiability, RuleVerifiability),
+    selected_rule(Rules, 'semantic-completeness', check_semantic_completeness, SemanticCompleteness).
+
+selected_rule(Rules, Name, Goal, Violations) :-
+    (   memberchk(Name, Rules)
+    ->  call(Goal, Violations)
+    ;   Violations = []
+    ).
+
+selected_rule_with_options(Rules, Name, Goal, Violations) :-
+    (   memberchk(Name, Rules)
+    ->  call(Goal, false, Violations)
+    ;   Violations = []
+    ).
+
 %% check_all_json_with_options(-JsonString, +RequireAdr)
 % Returns all violations as JSON string with options.
 % RequireAdr: if true, symbol-traceability also requires ADR constraints.

package/src/discovery.pl

@@ -143,7 +143,7 @@ coverage_rows(type, _Tags, _IncludePassing, _IncludeTransitive, _VerificationSna
 requirement_coverage_row(Tags, IncludeTransitive, ProofContext, Row) :-
     kb_entity(Id, req, Props),
     matches_tags(Tags, Props),
-    entity_title_status_source(Props, Title, Status, _Source),
+    entity_title_status_source(Props, Title, Status, Source),
     entity_priority(Props, Priority),
     count_distinct_targets(specified_by, Id, source, ScenarioCount),
     requirement_test_count(Id, TestCount),
@@ -156,6 +156,7 @@ requirement_coverage_row(Tags, IncludeTransitive, ProofContext, Row) :-
         type: req,
         title: Title,
         status: Status,
+        source: Source,
         priority: Priority,
         scenarioCount: ScenarioCount,
         testCount: TestCount,

package/src/kb.pl

@@ -1839,6 +1839,9 @@ literal_to_value(semantic_inventory, Literal, Value) :-
 literal_to_value(verification_receipts, Literal, Value) :-
     !,
     structured_literal_value(Literal, Value).
+literal_to_value(verification_contract, Literal, Value) :-
+    !,
+    structured_literal_value(Literal, Value).
 literal_to_value(_Key, Literal, Value) :-
     (   % Handle ^^/2 functor (RDF typed literal shorthand)
         Literal = ^^(StrVal, 'http://www.w3.org/2001/XMLSchema#string')

package/src/logic_ir.pl

@@ -530,7 +530,7 @@ rule_dependency_edge(
 logic_predicate_signature(atom(Namespace, Name, Args, _Polarity, _ClosedWorld), predicate(Namespace, Name, Arity)) :-
     length(Args, Arity).
 
-expression_dependency(atom(_Namespace, _Name, _Args, _Polarity, _ClosedWorld), Atom, positive) :-
+expression_dependency(Atom, Atom, positive) :-
     Atom = atom(_, _, _, _, _).
 expression_dependency(not(Atom), Atom, negative).
 expression_dependency(all(Items), Atom, Sign) :- member(Item, Items), expression_dependency(Item, Atom, Sign).

package/src/requirement_proof.pl

@@ -8,12 +8,12 @@
 ]).
 
 :- use_module(library(http/json)).
+:- use_module(library(crypto)).
 :- use_module(library(date)).
 :- use_module(library(pcre)).
 :- use_module('kb.pl').
 :- use_module('checks.pl', [
-    check_domain_contradictions/1,
-    check_domain_contradiction_witnesses/1,
+    check_domain_contradictions_and_witnesses/2,
     check_rule_safety/1,
     check_rule_verifiability/1
 ]).
@@ -25,8 +25,7 @@ requirement_proof_context(Context) :-
     requirement_proof_context(unknown, '1970-01-01T00:00:00Z', 604800, Context).
 
 requirement_proof_context(VerificationSnapshot, CheckedAt, MaxAgeSeconds, Context) :-
-    check_domain_contradictions(Contradictions),
-    check_domain_contradiction_witnesses(ContradictionWitnesses),
+    check_domain_contradictions_and_witnesses(Contradictions, ContradictionWitnesses),
     check_rule_safety(UnsafeRules),
     check_rule_verifiability(UnverifiableRules),
     normalize_atom(VerificationSnapshot, Snapshot),
@@ -52,6 +51,7 @@ requirement_proof(ReqId, _ReqProps, _Context, Proof) :-
         proofVersion: Version,
         proofStatus: not_applicable,
         proofGaps: [],
+        proofAdvisories: [],
         proofRepairs: [],
         proofStages: _{applicability: _{status: not_applicable}}
     }.
@@ -76,7 +76,7 @@ requirement_proof(ReqId, ReqProps, Context, Proof) :-
         productionSymbols: ProductionStage,
         sourceCoordinates: CoordinateStage
     },
-    proof_gaps(Stages, Gaps),
+    proof_issues(Stages, Gaps, Advisories),
     proof_repairs(Gaps, Repairs),
     proof_status(Stages, Status),
     proof_version(Version),
@@ -84,6 +84,7 @@ requirement_proof(ReqId, ReqProps, Context, Proof) :-
         proofVersion: Version,
         proofStatus: Status,
         proofGaps: Gaps,
+        proofAdvisories: Advisories,
         proofRepairs: Repairs,
         proofStages: Stages
     }.
@@ -224,6 +225,7 @@ logic_grounding_stage(ReqId, Props, Inventory, Context, Stage) :-
         InvalidRuleFactIds,
         Status
     ),
+    ground_source_refs(Evidence, GroundSources),
     Stage = _{
         status: Status,
         manifestClaims: ManifestKeys,
@@ -238,7 +240,8 @@ logic_grounding_stage(ReqId, Props, Inventory, Context, Stage) :-
         missingManifestClaims: MissingManifestKeys,
         extraManifestClaims: ExtraManifestKeys,
         undeclaredGroundClaims: UndeclaredGroundKeys,
-        invalidRuleFacts: InvalidRuleFactIds
+        invalidRuleFacts: InvalidRuleFactIds,
+        sources: GroundSources
     }.
 
 requirement_claim_keys(Props, true, Keys) :-
@@ -436,7 +439,8 @@ scenario_stage(ReqId, Stage, ScenarioIds) :-
         ScenarioIds0),
     sort(ScenarioIds0, ScenarioIds),
     (ScenarioIds = [] -> Status = missing ; Status = passed),
-    Stage = _{status: Status, scenarios: ScenarioIds}.
+    maplist(entity_source_ref, ScenarioIds, Sources),
+    Stage = _{status: Status, scenarios: ScenarioIds, sources: Sources}.
 
 scenario_test_stage(ScenarioIds, Stage, ScenarioTests) :-
     findall(TestId,
@@ -444,7 +448,8 @@ scenario_test_stage(ScenarioIds, Stage, ScenarioTests) :-
         ScenarioTests0),
     sort(ScenarioTests0, ScenarioTests),
     (ScenarioTests = [] -> Status = missing ; Status = passed),
-    Stage = _{status: Status, tests: ScenarioTests}.
+    maplist(entity_source_ref, ScenarioTests, Sources),
+    Stage = _{status: Status, tests: ScenarioTests, sources: Sources}.
 
 scenario_test(ScenarioId, TestId) :-
     kb_relationship(verified_by, ScenarioId, TestId),
@@ -460,9 +465,10 @@ passing_e2e_stage(ScenarioTests, Context, Stage, PassingE2eTests) :-
     evidence_tests_with_state(Evidence, stale, StaleReceiptTests),
     evidence_tests_with_state(Evidence, failed, FailedReceiptTests),
     evidence_tests_with_state(Evidence, invalid, InvalidReceiptTests),
+    evidence_tests_with_state(Evidence, contract_mismatch, ContractMismatchReceiptTests),
     evidence_tests_with_state(Evidence, snapshot_unavailable, SnapshotUnavailableTests),
     evidence_tests_with_state(Evidence, not_end_to_end, NonEndToEndTests),
-    passing_e2e_status(PassingE2eTests, InvalidReceiptTests, SnapshotUnavailableTests, Status),
+    passing_e2e_status(PassingE2eTests, InvalidReceiptTests, ContractMismatchReceiptTests, SnapshotUnavailableTests, Status),
     Stage = _{
         status: Status,
         tests: PassingE2eTests,
@@ -471,6 +477,7 @@ passing_e2e_stage(ScenarioTests, Context, Stage, PassingE2eTests) :-
         staleReceiptTests: StaleReceiptTests,
         failedReceiptTests: FailedReceiptTests,
         invalidReceiptTests: InvalidReceiptTests,
+        contractMismatchReceiptTests: ContractMismatchReceiptTests,
         snapshotUnavailableTests: SnapshotUnavailableTests,
         nonEndToEndTests: NonEndToEndTests,
         currentCodeSnapshot: Context.verificationSnapshot,
@@ -478,10 +485,11 @@ passing_e2e_stage(ScenarioTests, Context, Stage, PassingE2eTests) :-
         maxAgeSeconds: Context.verificationMaxAgeSeconds
     }.
 
-passing_e2e_status(Passing, _, _, passed) :- Passing \= [], !.
-passing_e2e_status([], Invalid, _, unresolved) :- Invalid \= [], !.
-passing_e2e_status([], _, SnapshotUnavailable, unresolved) :- SnapshotUnavailable \= [], !.
-passing_e2e_status([], _, _, missing).
+passing_e2e_status(Passing, _, _, _, passed) :- Passing \= [], !.
+passing_e2e_status([], Invalid, _, _, unresolved) :- Invalid \= [], !.
+passing_e2e_status([], _, ContractMismatch, _, unresolved) :- ContractMismatch \= [], !.
+passing_e2e_status([], _, _, SnapshotUnavailable, unresolved) :- SnapshotUnavailable \= [], !.
+passing_e2e_status([], _, _, _, missing).
 
 evidence_tests_with_state(Evidence, State, TestIds) :-
     findall(TestId,
@@ -497,26 +505,33 @@ test_receipt_evidence(Context, TestId, Evidence) :-
     ;   Context.verificationSnapshot == unknown
     ->  Evidence = _{testId: TestId, state: snapshot_unavailable, scope: Scope}
     ;   verification_receipt_entries(Props, Receipts, ReceiptPropertyPresent),
-        receipt_evidence_state(TestId, Scope, Receipts, ReceiptPropertyPresent, Context, Evidence)
+        receipt_evidence_state(TestId, Scope, Props, Receipts, ReceiptPropertyPresent, Context, Evidence)
     ).
 
-receipt_evidence_state(TestId, Scope, [], false, _Context,
+receipt_evidence_state(TestId, Scope, _Props, [], false, _Context,
         _{testId: TestId, state: missing, scope: Scope, receiptCount: 0}) :- !.
-receipt_evidence_state(TestId, Scope, Receipts, _Present, _Context,
+receipt_evidence_state(TestId, Scope, Props, Receipts, _Present, _Context,
         _{testId: TestId, state: invalid, scope: Scope, receiptCount: Count}) :-
     length(Receipts, Count),
-    (Receipts == []
-    ; member(Receipt, Receipts), \+ valid_receipt_shape(TestId, Scope, Receipt)
+    verification_contract_binding(Props, ContractBinding),
+    (ContractBinding == invalid
+    ; Receipts == []
+    ; member(Receipt, Receipts), \+ valid_receipt_shape(TestId, Receipt)
     ; \+ chronological_receipt_history(Receipts)),
     !.
-receipt_evidence_state(TestId, Scope, Receipts, _Present, Context, Evidence) :-
-    include(receipt_for_snapshot(Context.verificationSnapshot), Receipts, CurrentReceipts),
-    (   CurrentReceipts == []
+receipt_evidence_state(TestId, Scope, Props, Receipts, _Present, Context, Evidence) :-
+    include(receipt_for_snapshot(Context.verificationSnapshot), Receipts, SnapshotReceipts),
+    (   SnapshotReceipts == []
     ->  length(Receipts, Count),
         Evidence = _{testId: TestId, state: stale, scope: Scope, receiptCount: Count}
-    ;   latest_receipt(CurrentReceipts, Latest, FinishedStamp),
-        receipt_runtime_state(Latest, FinishedStamp, Context, State, AgeSeconds),
-        receipt_evidence_dict(TestId, Scope, Latest, State, AgeSeconds, Evidence)
+    ;   verification_contract_binding(Props, ContractBinding),
+        include(receipt_matches_current_binding(Scope, ContractBinding), SnapshotReceipts, CurrentReceipts),
+        (   CurrentReceipts == []
+        ->  receipt_contract_mismatch_evidence(TestId, Scope, SnapshotReceipts, ContractBinding, Evidence)
+        ;   latest_receipt(CurrentReceipts, Latest, FinishedStamp),
+            receipt_runtime_state(Latest, FinishedStamp, Context, State, AgeSeconds),
+            receipt_evidence_dict(TestId, Scope, Latest, State, AgeSeconds, Evidence)
+        )
     ).
 
 verification_receipt_entries(Props, Receipts, Present) :-
@@ -527,9 +542,10 @@ verification_receipt_entries(Props, Receipts, Present) :-
         Receipts = []
     ).
 
-valid_receipt_shape(TestId, Scope, Receipt) :-
+valid_receipt_shape(TestId, Receipt) :-
     inventory_entry_field(Receipt, version, RawVersion),
-    normalize_receipt_atom(RawVersion, 'kibi.verification-receipt.v1'),
+    normalize_receipt_atom(RawVersion, Version),
+    memberchk(Version, ['kibi.verification-receipt.v1', 'kibi.verification-receipt.v2']),
     inventory_entry_field(Receipt, receipt_id, RawReceiptId),
     normalize_receipt_atom(RawReceiptId, ReceiptId), valid_receipt_id(ReceiptId),
     inventory_entry_field(Receipt, test_id, RawTestId),
@@ -539,10 +555,11 @@ valid_receipt_shape(TestId, Scope, Receipt) :-
     inventory_entry_field(Receipt, command, RawCommand),
     normalize_receipt_atom(RawCommand, Command), Command \= '',
     inventory_entry_field(Receipt, scope, RawScope),
-    normalize_receipt_atom(RawScope, Scope),
+    normalize_receipt_atom(RawScope, ReceiptScope),
+    memberchk(ReceiptScope, [unit, integration, end_to_end]),
     inventory_entry_field(Receipt, outcome, RawOutcome),
     normalize_receipt_atom(RawOutcome, Outcome),
-    memberchk(Outcome, [passed, failed, errored, cancelled, skipped]),
+    memberchk(Outcome, [passed, failed, errored, cancelled, skipped, timed_out, interrupted]),
     inventory_entry_field(Receipt, code_snapshot, RawSnapshot),
     normalize_receipt_atom(RawSnapshot, Snapshot), valid_sha256(Snapshot),
     inventory_entry_field(Receipt, environment_hash, RawEnvironmentHash),
@@ -551,7 +568,53 @@ valid_receipt_shape(TestId, Scope, Receipt) :-
     normalize_receipt_atom(RawArtifactDigest, ArtifactDigest), valid_sha256(ArtifactDigest),
     receipt_timestamp(Receipt, started_at, StartedStamp),
     receipt_timestamp(Receipt, finished_at, FinishedStamp),
-    FinishedStamp >= StartedStamp.
+    FinishedStamp >= StartedStamp,
+    valid_receipt_version_fields(Version, Receipt).
+
+valid_receipt_version_fields('kibi.verification-receipt.v1', _Receipt).
+valid_receipt_version_fields('kibi.verification-receipt.v2', Receipt) :-
+    inventory_entry_field(Receipt, command_argv, RawCommandArgv),
+    is_list(RawCommandArgv),
+    RawCommandArgv \= [],
+    maplist(nonempty_receipt_atom, RawCommandArgv),
+    inventory_entry_field(Receipt, contract_hash, RawContractHash),
+    normalize_receipt_atom(RawContractHash, ContractHash),
+    valid_sha256(ContractHash),
+    inventory_entry_field(Receipt, case_results, RawCases),
+    is_list(RawCases),
+    RawCases \= [],
+    maplist(valid_receipt_case, RawCases),
+    findall(Key,
+        (member(Case, RawCases), receipt_case_key(Case, Key)), Keys),
+    sort(Keys, UniqueKeys),
+    length(Keys, KeyCount),
+    length(UniqueKeys, KeyCount).
+
+nonempty_receipt_atom(Value) :-
+    normalize_receipt_atom(Value, Atom),
+    Atom \= ''.
+
+valid_receipt_case(Case) :-
+    inventory_entry_field(Case, symbol_id, RawSymbolId),
+    nonempty_receipt_atom(RawSymbolId),
+    inventory_entry_field(Case, project, RawProject),
+    nonempty_receipt_atom(RawProject),
+    inventory_entry_field(Case, outcome, RawOutcome),
+    normalize_receipt_atom(RawOutcome, Outcome),
+    memberchk(Outcome, [passed, failed, timed_out, skipped, interrupted]),
+    inventory_entry_field(Case, retries, Retries),
+    normalize_integer(Retries, RetryCount),
+    RetryCount >= 0,
+    inventory_entry_field(Case, duration_ms, Duration),
+    normalize_integer(Duration, DurationMs),
+    DurationMs >= 0.
+
+receipt_case_key(Case, Key) :-
+    inventory_entry_field(Case, project, Project),
+    inventory_entry_field(Case, symbol_id, SymbolId),
+    normalize_receipt_atom(Project, ProjectAtom),
+    normalize_receipt_atom(SymbolId, SymbolAtom),
+    atomic_list_concat([ProjectAtom, SymbolAtom], '/', Key).
 
 valid_sha256(Value) :-
     atom_length(Value, 64),
@@ -584,6 +647,82 @@ receipt_for_snapshot(Snapshot, Receipt) :-
     inventory_entry_field(Receipt, code_snapshot, RawSnapshot),
     normalize_receipt_atom(RawSnapshot, Snapshot).
 
+receipt_matches_current_binding(Scope, ContractBinding, Receipt) :-
+    inventory_entry_field(Receipt, scope, RawScope),
+    normalize_receipt_atom(RawScope, Scope),
+    receipt_matches_current_contract(ContractBinding, Receipt).
+
+receipt_matches_current_contract(none, _Receipt).
+receipt_matches_current_contract(hash(ExpectedHash), Receipt) :-
+    inventory_entry_field(Receipt, version, RawVersion),
+    normalize_receipt_atom(RawVersion, 'kibi.verification-receipt.v2'),
+    inventory_entry_field(Receipt, contract_hash, RawContractHash),
+    normalize_receipt_atom(RawContractHash, ExpectedHash).
+
+receipt_contract_mismatch_evidence(TestId, Scope, Receipts, ContractBinding, Evidence) :-
+    length(Receipts, Count),
+    findall(Hash,
+        (member(Receipt, Receipts),
+         inventory_entry_field(Receipt, contract_hash, RawHash),
+         normalize_receipt_atom(RawHash, Hash)),
+        Hashes0),
+    sort(Hashes0, Hashes),
+    current_contract_hash_value(ContractBinding, CurrentContractHash),
+    Evidence = _{
+        testId: TestId,
+        state: contract_mismatch,
+        scope: Scope,
+        receiptCount: Count,
+        currentContractHash: CurrentContractHash,
+        receiptContractHashes: Hashes
+    }.
+
+current_contract_hash_value(hash(Hash), Hash).
+current_contract_hash_value(none, none).
+
+verification_contract_binding(Props, Binding) :-
+    (   memberchk(verification_contract=RawContract, Props)
+    ->  (verification_contract_hash(RawContract, Hash) -> Binding = hash(Hash) ; Binding = invalid)
+    ;   Binding = none
+    ).
+
+verification_contract_hash(RawContract, Hash) :-
+    verification_contract_dict(RawContract, Contract),
+    canonical_json_value(Contract, Canonical),
+    crypto_data_hash(Canonical, Hash, [algorithm(sha256), encoding(utf8)]).
+
+verification_contract_dict(^^(Value, _), Contract) :- !,
+    verification_contract_dict(Value, Contract).
+verification_contract_dict(literal(type(_, Value)), Contract) :- !,
+    verification_contract_dict(Value, Contract).
+verification_contract_dict(literal(Value), Contract) :- !,
+    verification_contract_dict(Value, Contract).
+verification_contract_dict(Contract, Contract) :-
+    is_dict(Contract), !.
+verification_contract_dict(Raw, Contract) :-
+    (atom(Raw) ; string(Raw)),
+    catch(atom_json_dict(Raw, Contract, [value_string_as(string)]), _, fail),
+    is_dict(Contract).
+
+canonical_json_value(Value, Json) :-
+    is_dict(Value), !,
+    dict_pairs(Value, _, Pairs),
+    maplist(canonical_json_pair, Pairs, Parts),
+    atomics_to_string(Parts, ",", Body),
+    format(string(Json), "{~s}", [Body]).
+canonical_json_value(Value, Json) :-
+    is_list(Value), !,
+    maplist(canonical_json_value, Value, Parts),
+    atomics_to_string(Parts, ",", Body),
+    format(string(Json), "[~s]", [Body]).
+canonical_json_value(Value, Json) :-
+    with_output_to(string(Json), json_write(current_output, Value, [width(0)])).
+
+canonical_json_pair(Key-Value, Json) :-
+    with_output_to(string(KeyJson), json_write(current_output, Key, [width(0)])),
+    canonical_json_value(Value, ValueJson),
+    format(string(Json), "~s:~s", [KeyJson, ValueJson]).
+
 latest_receipt(Receipts, Latest, FinishedStamp) :-
     findall(Stamp-Receipt,
         (member(Receipt, Receipts), receipt_timestamp(Receipt, finished_at, Stamp)),
@@ -662,7 +801,7 @@ test_scope(Props, end_to_end) :-
     !.
 test_scope(_, unknown).
 
-executable_symbol_stage([], _{status: blocked, symbols: [], missingTests: []}, []).
+executable_symbol_stage([], _{status: blocked, symbols: [], missingTests: [], coordinates: []}, []).
 executable_symbol_stage(PassingE2eTests, Stage, Symbols) :-
     PassingE2eTests \= [],
     findall(SymbolId,
@@ -673,7 +812,8 @@ executable_symbol_stage(PassingE2eTests, Stage, Symbols) :-
     sort(Symbols0, Symbols),
     include(test_missing_executable_symbol, PassingE2eTests, MissingTests),
     (MissingTests = [] -> Status = passed ; Status = missing),
-    Stage = _{status: Status, symbols: Symbols, missingTests: MissingTests}.
+    maplist(symbol_coordinate_ref, Symbols, Coordinates),
+    Stage = _{status: Status, symbols: Symbols, missingTests: MissingTests, coordinates: Coordinates}.
 
 test_missing_executable_symbol(TestId) :-
     \+ (kb_relationship(executable_for, SymbolId, TestId), kb_entity(SymbolId, symbol, _)).
@@ -683,16 +823,36 @@ production_symbol_stage(ReqId, PassingE2eTests, Stage, ProductionSymbols) :-
         (kb_relationship(implements, SymbolId, ReqId),
          kb_entity(SymbolId, symbol, _),
          \+ kb:executable_test_symbol(SymbolId)),
-        Production0),
-    sort(Production0, ProductionSymbols),
+        Implementing0),
+    sort(Implementing0, ImplementingSymbols),
+    include(type_shape_symbol_with_structural_contract, ImplementingSymbols, StructuralSymbols),
+    exclude(type_shape_symbol_with_structural_contract, ImplementingSymbols, ProductionSymbols),
     include(symbol_not_covered_by_tests(PassingE2eTests), ProductionSymbols, UncoveredSymbols),
-    production_stage_status(ProductionSymbols, PassingE2eTests, UncoveredSymbols, Status),
-    Stage = _{status: Status, symbols: ProductionSymbols, uncoveredSymbols: UncoveredSymbols}.
+    production_stage_status(ProductionSymbols, StructuralSymbols, PassingE2eTests, UncoveredSymbols, Status),
+    maplist(symbol_coordinate_ref, ProductionSymbols, Coordinates),
+    Stage = _{
+        status: Status,
+        symbols: ProductionSymbols,
+        structuralSymbols: StructuralSymbols,
+        uncoveredSymbols: UncoveredSymbols,
+        coordinates: Coordinates
+    }.
 
-production_stage_status([], _, _, missing) :- !.
-production_stage_status(_, [], _, blocked) :- !.
-production_stage_status(_, _, [], passed) :- !.
-production_stage_status(_, _, _, missing).
+type_shape_symbol_with_structural_contract(SymbolId) :-
+    kb_entity(SymbolId, symbol, SymbolProps),
+    memberchk(symbol_role=RawRole, SymbolProps),
+    normalize_atom(RawRole, 'type-shape'),
+    kb_relationship(covered_by, SymbolId, TestId),
+    kb_entity(TestId, test, TestProps),
+    test_scope(TestProps, unit),
+    memberchk(status=RawStatus, TestProps),
+    normalize_atom(RawStatus, Status),
+    memberchk(Status, [active, passing]).
+
+production_stage_status([], [], _, _, missing) :- !.
+production_stage_status(_, _, [], _, blocked) :- !.
+production_stage_status(_, _, _, [], passed) :- !.
+production_stage_status(_, _, _, _, missing).
 
 symbol_not_covered_by_tests(Tests, SymbolId) :-
     \+ (member(TestId, Tests), kb_relationship(covered_by, SymbolId, TestId)).
@@ -707,11 +867,15 @@ source_coordinate_stage(ReqProps, ExecutableSymbols, ProductionSymbols, Stage) :
     ;   RequirementSource = present,
         coordinate_stage_status(Symbols, MissingSymbols, Status)
     ),
+    requirement_source_path(ReqProps, RequirementPath),
+    maplist(symbol_coordinate_ref, Symbols, Coordinates),
     Stage = _{
         status: Status,
         requirementSource: RequirementSource,
+        requirementPath: RequirementPath,
         symbols: Symbols,
-        missingSymbols: MissingSymbols
+        missingSymbols: MissingSymbols,
+        coordinates: Coordinates
     }.
 
 coordinate_stage_status([], _, blocked) :- !.
@@ -724,7 +888,7 @@ symbol_missing_coordinates(SymbolId) :-
 
 valid_symbol_coordinates(Props) :-
     memberchk(sourceFile=RawSourceFile, Props),
-    normalize_atom(RawSourceFile, SourceFile),
+    source_path_atom(RawSourceFile, SourceFile),
     SourceFile \= '',
     memberchk(sourceLine=RawLine, Props),
     memberchk(sourceColumn=RawColumn, Props),
@@ -739,10 +903,66 @@ valid_symbol_coordinates(Props) :-
     EndLine >= Line,
     EndColumn >= 0.
 
-nonempty_source(Props) :-
+% Prefer sourceFile, then source, without URI-basename stripping. Paths must
+% remain inspectable coordinates for report linking.
+proof_source_property(Props, RawSource) :-
+    memberchk(sourceFile=RawSource, Props),
+    source_path_atom(RawSource, _),
+    !.
+proof_source_property(Props, RawSource) :-
     memberchk(source=RawSource, Props),
-    normalize_atom(RawSource, Source),
-    Source \= ''.
+    source_path_atom(RawSource, _).
+
+nonempty_source(Props) :-
+    proof_source_property(Props, _).
+
+requirement_source_path(Props, Path) :-
+    proof_source_property(Props, RawSource),
+    source_path_atom(RawSource, Path),
+    !.
+requirement_source_path(_, '').
+
+entity_source_path(Id, Path) :-
+    kb_entity(Id, _, Props),
+    requirement_source_path(Props, Path).
+
+entity_source_ref(Id, _{id: Id, path: Path}) :-
+    entity_source_path(Id, Path).
+
+ground_source_refs(Evidence, Refs) :-
+    findall(Ref,
+        (member(Item, Evidence),
+         entity_source_ref(Item.factId, Ref),
+         Ref.path \= ''),
+        Refs0),
+    sort(Refs0, Refs).
+
+symbol_coordinate_ref(SymbolId, Ref) :-
+    kb_entity(SymbolId, symbol, Props),
+    memberchk(sourceFile=RawFile, Props),
+    source_path_atom(RawFile, File),
+    File \= '',
+    !,
+    (   valid_symbol_coordinates(Props)
+    ->  memberchk(sourceLine=RawLine, Props),
+        memberchk(sourceColumn=RawColumn, Props),
+        memberchk(sourceEndLine=RawEndLine, Props),
+        memberchk(sourceEndColumn=RawEndColumn, Props),
+        normalize_integer(RawLine, Line),
+        normalize_integer(RawColumn, Column),
+        normalize_integer(RawEndLine, EndLine),
+        normalize_integer(RawEndColumn, EndColumn),
+        Ref = _{
+            id: SymbolId,
+            path: File,
+            line: Line,
+            column: Column,
+            endLine: EndLine,
+            endColumn: EndColumn
+        }
+    ;   Ref = _{id: SymbolId, path: File}
+    ).
+symbol_coordinate_ref(SymbolId, _{id: SymbolId, path: ''}).
 
 proof_status(Stages, unresolved) :-
     Stages.contradictions.status == blocked,
@@ -762,7 +982,36 @@ stage_dict(Stages, Stage) :-
     member(_-Stage, Pairs).
 
 proof_gaps(Stages, Gaps) :-
-    findall(Gap, (gap_definition(Gap, _, _, _), proof_gap_present(Gap, Stages)), Gaps).
+    proof_issues(Stages, Gaps, _).
+
+proof_advisories(Stages, Advisories) :-
+    proof_issues(Stages, _, Advisories).
+
+% implements REQ-kibi-conservative-requirement-proof
+% proofGaps are blocking only. Receipt-completeness codes become
+% proofAdvisories when passingE2e already supplies strict proof.
+% Invariant: proofStatus == proven implies proofGaps == [].
+proof_issues(Stages, Gaps, Advisories) :-
+    findall(Gap,
+        (gap_definition(Gap, _, _, _),
+         proof_gap_present(Gap, Stages),
+         \+ proof_issue_advisory(Gap, Stages)),
+        Gaps),
+    findall(Gap,
+        (gap_definition(Gap, _, _, _),
+         proof_gap_present(Gap, Stages),
+         proof_issue_advisory(Gap, Stages)),
+        Advisories).
+
+receipt_completeness_issue(missing_verification_receipt).
+receipt_completeness_issue(stale_verification_receipt).
+receipt_completeness_issue(failed_verification_receipt).
+receipt_completeness_issue(invalid_verification_receipt).
+receipt_completeness_issue(verification_contract_mismatch).
+
+proof_issue_advisory(Gap, Stages) :-
+    receipt_completeness_issue(Gap),
+    Stages.passingE2e.status == passed.
 
 proof_gap_present(missing_semantic_inventory, Stages) :- Stages.semanticInventory.propositionCount =:= 0.
 proof_gap_present(incomplete_semantic_inventory, Stages) :- Stages.semanticInventory.missingCount > 0.
@@ -783,9 +1032,12 @@ proof_gap_present(missing_verification_receipt, Stages) :- Stages.passingE2e.mis
 proof_gap_present(stale_verification_receipt, Stages) :- Stages.passingE2e.staleReceiptTests \= [].
 proof_gap_present(failed_verification_receipt, Stages) :- Stages.passingE2e.failedReceiptTests \= [].
 proof_gap_present(invalid_verification_receipt, Stages) :- Stages.passingE2e.invalidReceiptTests \= [].
+proof_gap_present(verification_contract_mismatch, Stages) :- Stages.passingE2e.contractMismatchReceiptTests \= [].
 proof_gap_present(verification_snapshot_unavailable, Stages) :- Stages.passingE2e.snapshotUnavailableTests \= [].
 proof_gap_present(missing_executable_test_symbol, Stages) :- Stages.executableSymbols.status == missing.
-proof_gap_present(missing_production_symbol, Stages) :- Stages.productionSymbols.symbols == [].
+proof_gap_present(missing_production_symbol, Stages) :-
+    Stages.productionSymbols.symbols == [],
+    Stages.productionSymbols.structuralSymbols == [].
 proof_gap_present(missing_production_symbol_coverage, Stages) :- Stages.productionSymbols.uncoveredSymbols \= [].
 proof_gap_present(missing_symbol_coordinates, Stages) :- Stages.sourceCoordinates.missingSymbols \= [].
 proof_gap_present(missing_requirement_source, Stages) :- Stages.sourceCoordinates.requirementSource == missing.
@@ -803,14 +1055,15 @@ gap_definition(contradiction_check_incomplete, 41, contradictions, "Complete log
 gap_definition(missing_scenario, 50, scenarios, "Add a specified_by scenario for the requirement.").
 gap_definition(missing_scenario_test, 51, scenario_tests, "Link the scenario to a test with verified_by or validates.").
 gap_definition(missing_passing_e2e, 52, passing_e2e, "Record fresh passing end-to-end evidence on a scenario-backed test.").
-gap_definition(missing_verification_receipt, 53, passing_e2e, "Record a kibi.verification-receipt.v1 result for the scenario-backed E2E test.").
+gap_definition(missing_verification_receipt, 53, passing_e2e, "Run the exact current verification contract through kibi verify and append its kibi.verification-receipt.v2 result for the scenario-backed E2E test.").
 gap_definition(stale_verification_receipt, 54, passing_e2e, "Re-run the E2E test against the current code snapshot and append its receipt.").
 gap_definition(failed_verification_receipt, 55, passing_e2e, "Repair the failing E2E behavior and append a newer passing receipt for the same snapshot.").
 gap_definition(invalid_verification_receipt, 56, passing_e2e, "Repair malformed, future-dated, mismatched, or otherwise uncheckable receipt evidence.").
-gap_definition(verification_snapshot_unavailable, 57, passing_e2e, "Run coverage through a CLI or MCP runtime that exposes the deterministic workspace snapshot.").
+gap_definition(verification_contract_mismatch, 57, passing_e2e, "Run the current verification contract and append its receipt without rewriting historical evidence.").
+gap_definition(verification_snapshot_unavailable, 58, passing_e2e, "Run coverage through a CLI or MCP runtime that exposes the deterministic workspace snapshot.").
 gap_definition(missing_executable_test_symbol, 60, executable_symbols, "Link executable test code to every qualifying E2E test with executable_for.").
 gap_definition(missing_production_symbol, 70, production_symbols, "Link at least one production symbol to the requirement with implements.").
-gap_definition(missing_production_symbol_coverage, 71, production_symbols, "Link every implementing production symbol to a qualifying E2E test with covered_by.").
+gap_definition(missing_production_symbol_coverage, 71, production_symbols, "Link every runtime implementing production symbol to a qualifying E2E test with covered_by; type-shape symbols retain structural unit contracts instead.").
 gap_definition(missing_symbol_coordinates, 80, source_coordinates, "Refresh and persist exact coordinates for every proof-bearing symbol.").
 gap_definition(missing_requirement_source, 81, source_coordinates, "Bind the requirement to its current source document.").
 
@@ -822,6 +1075,10 @@ proof_repairs(Gaps, Repairs) :-
 normalize_atom(Value, Atom) :-
     kb:normalize_term_atom(Value, Atom).
 
+source_path_atom(Value, Atom) :-
+    kb:source_value_atom(Value, Atom),
+    Atom \= ''.
+
 normalize_atom_list(Value, Atoms) :-
     kb:normalize_term_atom_list(Value, Atoms).
 

package/src/status.pl

@@ -19,12 +19,16 @@ status_meta_dict(StatusDict) :-
     snapshot_id(SnapshotId),
     synced_at(DataFile, SyncedAt),
     freshness_state(DataFile, Dirty, SyncState),
+    stale_reasons(StaleReasons, StaleReasonCount, StaleReasonsTruncated),
     StatusDict = _{
         branch: Branch,
         snapshotId: SnapshotId,
         syncedAt: SyncedAt,
         dirty: Dirty,
         syncState: SyncState,
+        staleReasons: StaleReasons,
+        staleReasonCount: StaleReasonCount,
+        staleReasonsTruncated: StaleReasonsTruncated,
         kbPath: KbPath,
         lastSyncSource: persisted
     }.
@@ -37,6 +41,9 @@ status_meta_dict(StatusDict) :-
         syncedAt: null,
         dirty: false,
         syncState: unknown,
+        staleReasons: [],
+        staleReasonCount: 0,
+        staleReasonsTruncated: false,
         kbPath: KbPath,
         lastSyncSource: unknown
     }.
@@ -104,9 +111,90 @@ freshness_state(DataFile, false, fresh) :-
     !.
 freshness_state(_, true, unknown).
 
+stale_reasons(Reasons, Count, Truncated) :-
+    findall(Reason, stale_indexed_source_reason(Reason), IndexedReasons),
+    findall(Reason, stale_knowledge_lane_reason(Reason), KnowledgeReasons),
+    findall(Reason, stale_documentation_reason(Reason), DocumentationReasons),
+    append(IndexedReasons, KnowledgeReasons, IndexedAndKnowledge),
+    append(IndexedAndKnowledge, DocumentationReasons, Reasons0),
+    sort(Reasons0, Sorted),
+    length(Sorted, Count),
+    (   Count > 200
+    ->  length(Reasons, 200), append(Reasons, _, Sorted), Truncated = true
+    ;   Reasons = Sorted, Truncated = false
+    ).
+
+stale_indexed_source_reason(Reason) :-
+    attached_workspace_root(WorkspaceRoot),
+    kb:kb_indexed_sources(Sources),
+    member(SourceAtom, Sources),
+    repo_relative_source(SourceAtom, RelativeSource),
+    directory_file_path(WorkspaceRoot, RelativeSource, SourcePath),
+    (   exists_file(SourcePath)
+    ->  time_file(SourcePath, FileTime),
+        kb_snapshot_time(SnapshotTime),
+        FileTime > SnapshotTime,
+        Code = indexed_source_newer
+    ;   exists_directory(SourcePath)
+    ->  fail
+    ;   Code = indexed_source_missing
+    ),
+    entity_ids_for_source(RelativeSource, EntityIds),
+    Reason = _{code: Code, path: RelativeSource, entityIds: EntityIds}.
+
+stale_knowledge_lane_reason(Reason) :-
+    attached_workspace_root(WorkspaceRoot),
+    knowledge_lane(Lane),
+    directory_file_path(WorkspaceRoot, '.kb', KbRoot),
+    directory_file_path(KbRoot, Lane, LaneRoot),
+    exists_directory(LaneRoot),
+    kb_snapshot_time(SnapshotTime),
+    directory_tree_newer_path(LaneRoot, SnapshotTime, Path),
+    workspace_relative_path(WorkspaceRoot, Path, RelativePath),
+    entity_ids_for_source(RelativePath, EntityIds),
+    Reason = _{code: knowledge_source_newer, path: RelativePath, entityIds: EntityIds}.
+
+stale_documentation_reason(Reason) :-
+    attached_workspace_root(WorkspaceRoot),
+    directory_file_path(WorkspaceRoot, 'documentation', DocumentationRoot),
+    exists_directory(DocumentationRoot),
+    kb_snapshot_time(SnapshotTime),
+    directory_tree_newer_path(DocumentationRoot, SnapshotTime, Path),
+    workspace_relative_path(WorkspaceRoot, Path, RelativePath),
+    entity_ids_for_source(RelativePath, EntityIds),
+    Reason = _{code: documentation_source_newer, path: RelativePath, entityIds: EntityIds}.
+
+kb_snapshot_time(SnapshotTime) :-
+    kb:kb_attached(KbPath),
+    (   directory_file_path(KbPath, 'CURRENT', DataFile), exists_file(DataFile)
+    ->  time_file(DataFile, SnapshotTime)
+    ;   directory_file_path(KbPath, 'kb.rdf', DataFile), exists_file(DataFile)
+    ->  time_file(DataFile, SnapshotTime)
+    ;   SnapshotTime = 0
+    ).
+
+entity_ids_for_source(RelativeSource, EntityIds) :-
+    findall(Id,
+        (kb_entity(Id, _Type, Props),
+         entity_source_property(Props, RawSource),
+         source_value_atom(RawSource, SourceAtom),
+         repo_relative_source(SourceAtom, RelativeSource),
+         Id \= '') ,
+        Ids0),
+    sort(Ids0, EntityIds).
+
+entity_source_property(Props, RawSource) :-
+    memberchk(sourceFile=RawSource, Props),
+    !.
+entity_source_property(Props, RawSource) :-
+    memberchk(source=RawSource, Props).
+
 workspace_state_changed(SnapshotTime) :-
     workspace_source_changed(SnapshotTime),
     !.
+workspace_state_changed(SnapshotTime) :-
+    knowledge_lane_tree_changed(SnapshotTime),
+    !.
 workspace_state_changed(SnapshotTime) :-
     documentation_tree_changed(SnapshotTime),
     !.
@@ -126,6 +214,15 @@ workspace_source_changed(SnapshotTime) :-
     ),
     !.
 
+knowledge_lane_tree_changed(SnapshotTime) :-
+    attached_workspace_root(WorkspaceRoot),
+    knowledge_lane(Lane),
+    directory_file_path(WorkspaceRoot, '.kb', KbRoot),
+    directory_file_path(KbRoot, Lane, LaneRoot),
+    exists_directory(LaneRoot),
+    directory_tree_newer(LaneRoot, SnapshotTime),
+    !.
+
 documentation_tree_changed(SnapshotTime) :-
     attached_workspace_root(WorkspaceRoot),
     directory_file_path(WorkspaceRoot, 'documentation', DocumentationRoot),
@@ -140,6 +237,7 @@ directory_tree_newer(Path, SnapshotTime) :-
     time_file(Path, EntryTime),
     EntryTime > SnapshotTime,
     !.
+
 directory_tree_newer(Path, SnapshotTime) :-
     exists_directory(Path),
     directory_files(Path, Entries),
@@ -150,6 +248,21 @@ directory_tree_newer(Path, SnapshotTime) :-
     directory_tree_newer(ChildPath, SnapshotTime),
     !.
 
+directory_tree_newer_path(Path, SnapshotTime, Path) :-
+    exists_file(Path),
+    entity_documentation_file(Path),
+    \+ ignored_documentation_file(Path),
+    time_file(Path, EntryTime),
+    EntryTime > SnapshotTime.
+directory_tree_newer_path(Path, SnapshotTime, ChildPath) :-
+    exists_directory(Path),
+    directory_files(Path, Entries),
+    member(Entry, Entries),
+    Entry \= '.',
+    Entry \= '..',
+    directory_file_path(Path, Entry, Candidate),
+    directory_tree_newer_path(Candidate, SnapshotTime, ChildPath).
+
 attached_workspace_root(WorkspaceRoot) :-
     kb:kb_attached(KbPath),
     branch_workspace_from_kb_path(KbPath, _Branch, WorkspaceRoot).
@@ -219,8 +332,20 @@ source_value_atom(Val, Atom) :-
     term_string(Val, Str),
     atom_string(Atom, Str).
 
+knowledge_lane(requirements).
+knowledge_lane(scenarios).
+knowledge_lane(tests).
+knowledge_lane(facts).
+knowledge_lane(adr).
+knowledge_lane(flags).
+knowledge_lane(events).
+
 ignored_documentation_file(Path) :-
     file_base_name(Path, 'README.md').
+ignored_documentation_file(Path) :-
+    sub_atom(Path, _, _, _, '/tests/e2e/').
+ignored_documentation_file(Path) :-
+    sub_atom(Path, _, _, _, '/tests/benchmarks/').
 
 entity_documentation_file(Path) :-
     read_file_to_string(Path, Content, []),