[EPIC][expert] Project symbolic knowledge expert: fresh source facts, relations, provenance, and explainable project queries #418

New issue

Open

opened 2026-09-08 01:29:22 +00:00 by nsaspy · 1 comment

nsaspy commented

2026-09-08 01:29:22 +00:00

Owner

Parent: #376
Depends on: #377
Consumes: #93, #96–#99, existing Project/source APIs

Goal

Add a Project Symbolic Knowledge Expert that answers project/source questions from fresh, provenance-carrying Prolog knowledge rather than forcing callers or models to rediscover repository structure from raw text.

This is the canonical specialist for questions such as:

What defines symbol X?
Where is it referenced?
What imports/calls/depends on Y?
Which files implement requirement Z?
What changed in the source knowledge generation?
Is this evidence current or stale?
What project facts support this conclusion?

It is read/knowledge oriented. It does not own filesystem mutation.

Source truth

Reuse #93's Project/source model and the #96–#99 pipeline:

source bytes
  -> versioned parse/CST
  -> query captures
  -> symbols/references/calls/imports/etc.
  -> derived Prolog relations
  -> coherent project snapshot
  -> Project Knowledge Expert

For Prolog source, use SWI-native xref/source semantics where stronger than generic Tree-sitter extraction.

Do not build a competing index or source ontology solely for this expert.

Responsibilities

acquire/require a coherent current project snapshot;
answer normalized symbol/source/dependency/relationship queries;
resolve symbol_ref / source-span style references used by plans and Write Expert;
distinguish direct observations from derived relations;
detect stale/incomplete/ambiguous evidence;
derive higher-order project facts using ordinary Prolog rules/tabling where useful;
expose provenance and explanation paths;
identify missing knowledge and delegate to Retrieval Expert or plan-native index where appropriate;
support incremental invalidation/current-generation semantics after writes.

Knowledge classes

Keep explicit distinctions between:

Project/File identities
source content hashes/generations
parse/grammar/extractor generations
CST observations
symbols/definitions/references
calls/imports/exports/dependencies
configuration/build/test metadata observations
inferred project relations
SPEC-linked evidence
stale/ambiguous/unknown facts

Do not flatten all facts into untyped strings.

Expert goals

Conceptual forms:

project_fact(Query).
resolve_symbol(SymbolRef).
resolve_source_span(SymbolOrNode).
project_dependency(Source, Target).
project_evidence(Requirement).
project_change_impact(Change).
project_unknown(Query).
why_project_fact(Fact).

Exact vocabulary follows the source/project API and should stay extensible.

Freshness is a correctness requirement

A supposedly current answer must be bound to the current coherent source snapshot. Stale facts may be inspectable but cannot silently satisfy a query requiring current evidence.

The expert should return structured unknown, stale, ambiguous, or incomplete states instead of inventing certainty.

Symbolic reasoning

Use Prolog strengths aggressively:

transitive dependency closure;
call/import graph traversal;
tabling/memoization;
reachability and impact analysis;
rule-based project classification;
constraint filtering by file/language/generation/source;
contradiction detection between observations;
provenance-path reconstruction.

Normal expert reasoning uses zero model calls.

An optional LLM fallback may enrich fuzzy semantic mapping only when explicitly configured; any resulting candidate relation must remain distinguishable from authoritative parser/xref observations and carry fallback provenance.

Cooperation

Planner Expert asks what is already true / where work belongs.
Git Expert contributes repository-history/worktree observations, not source semantic truth.
Write Expert resolves targets/preimages through this expert before producing edits.
Verify Expert consumes current project facts as evidence.
Repair Expert uses dependency/impact knowledge to localize failures.
Retrieval Expert can fill knowledge gaps from other indexed/document sources.

Acceptance

Queries a fixed project fixture with zero model calls.
Resolves definitions/references and returns exact source provenance.
Traverses at least one multi-hop dependency/call/import relation symbolically.
Two projects cannot leak facts into each other.
Stale generation cannot answer a current query as success.
Ambiguous symbol resolution remains explicit.
Derived relation identifies the underlying observed facts/provenance used.
A source change invalidates or supersedes affected knowledge deterministically.
Write Expert can consume a resolved current source span/preimage reference.
Verify Expert can consume an evidence reference without rereading arbitrary prose.
No project source/config text becomes trusted executable Prolog merely by indexing it.

Non-goals

No source mutation.
No ambient Git/filesystem authority.
No separate source index parallel to #93/#96–#99.

Refs #376 #377 #93 #96 #97 #98 #99 #288

Parent: #376 Depends on: #377 Consumes: #93, #96–#99, existing Project/source APIs ## Goal Add a **Project Symbolic Knowledge Expert** that answers project/source questions from fresh, provenance-carrying Prolog knowledge rather than forcing callers or models to rediscover repository structure from raw text. This is the canonical specialist for questions such as: ```text What defines symbol X? Where is it referenced? What imports/calls/depends on Y? Which files implement requirement Z? What changed in the source knowledge generation? Is this evidence current or stale? What project facts support this conclusion? ``` It is read/knowledge oriented. It does not own filesystem mutation. ## Source truth Reuse #93's Project/source model and the #96–#99 pipeline: ```text source bytes -> versioned parse/CST -> query captures -> symbols/references/calls/imports/etc. -> derived Prolog relations -> coherent project snapshot -> Project Knowledge Expert ``` For Prolog source, use SWI-native xref/source semantics where stronger than generic Tree-sitter extraction. Do not build a competing index or source ontology solely for this expert. ## Responsibilities - acquire/require a coherent current project snapshot; - answer normalized symbol/source/dependency/relationship queries; - resolve `symbol_ref` / source-span style references used by plans and Write Expert; - distinguish direct observations from derived relations; - detect stale/incomplete/ambiguous evidence; - derive higher-order project facts using ordinary Prolog rules/tabling where useful; - expose provenance and explanation paths; - identify missing knowledge and delegate to Retrieval Expert or plan-native `index` where appropriate; - support incremental invalidation/current-generation semantics after writes. ## Knowledge classes Keep explicit distinctions between: ```text Project/File identities source content hashes/generations parse/grammar/extractor generations CST observations symbols/definitions/references calls/imports/exports/dependencies configuration/build/test metadata observations inferred project relations SPEC-linked evidence stale/ambiguous/unknown facts ``` Do not flatten all facts into untyped strings. ## Expert goals Conceptual forms: ```prolog project_fact(Query). resolve_symbol(SymbolRef). resolve_source_span(SymbolOrNode). project_dependency(Source, Target). project_evidence(Requirement). project_change_impact(Change). project_unknown(Query). why_project_fact(Fact). ``` Exact vocabulary follows the source/project API and should stay extensible. ## Freshness is a correctness requirement A supposedly current answer must be bound to the current coherent source snapshot. Stale facts may be inspectable but cannot silently satisfy a query requiring current evidence. The expert should return structured `unknown`, `stale`, `ambiguous`, or `incomplete` states instead of inventing certainty. ## Symbolic reasoning Use Prolog strengths aggressively: - transitive dependency closure; - call/import graph traversal; - tabling/memoization; - reachability and impact analysis; - rule-based project classification; - constraint filtering by file/language/generation/source; - contradiction detection between observations; - provenance-path reconstruction. Normal expert reasoning uses zero model calls. An optional LLM fallback may enrich fuzzy semantic mapping only when explicitly configured; any resulting candidate relation must remain distinguishable from authoritative parser/xref observations and carry fallback provenance. ## Cooperation - **Planner Expert** asks what is already true / where work belongs. - **Git Expert** contributes repository-history/worktree observations, not source semantic truth. - **Write Expert** resolves targets/preimages through this expert before producing edits. - **Verify Expert** consumes current project facts as evidence. - **Repair Expert** uses dependency/impact knowledge to localize failures. - **Retrieval Expert** can fill knowledge gaps from other indexed/document sources. ## Acceptance - [ ] Queries a fixed project fixture with zero model calls. - [ ] Resolves definitions/references and returns exact source provenance. - [ ] Traverses at least one multi-hop dependency/call/import relation symbolically. - [ ] Two projects cannot leak facts into each other. - [ ] Stale generation cannot answer a `current` query as success. - [ ] Ambiguous symbol resolution remains explicit. - [ ] Derived relation identifies the underlying observed facts/provenance used. - [ ] A source change invalidates or supersedes affected knowledge deterministically. - [ ] Write Expert can consume a resolved current source span/preimage reference. - [ ] Verify Expert can consume an evidence reference without rereading arbitrary prose. - [ ] No project source/config text becomes trusted executable Prolog merely by indexing it. ## Non-goals - No source mutation. - No ambient Git/filesystem authority. - No separate source index parallel to #93/#96–#99. Refs #376 #377 #93 #96 #97 #98 #99 #288

nsaspy commented

2026-09-08 01:46:34 +00:00

Author

Owner

Sibling boundary: #388 now owns generic corpus/document/log symbolicization (LLM logs, web results, reports, arbitrary text) under immutable schemas + append-only provenance. #380 remains authoritative for project/source-code semantics. Cross-links should occur through normalized evidence refs/queries rather than merging both domains into one universal ontology.