Towards systematic evidence

docs/characteristic-evidence-model.md

@@ -0,0 +1,64 @@
+# Characteristic And Evidence Model
+
+The registry should treat a repository profile as a characteristic tree.
+
+## Characteristics
+
+A characteristic is an interpreted claim about a repository. The current concrete
+levels are:
+
+- Scope: the single root characteristic for the repository.
+- Ability: a high-level thing the repository is meant to enable.
+- Capability: a more specific capacity that contributes to an ability.
+- Feature: a concrete user-facing, operational, interface, or implementation
+  feature that contributes to a capability.
+
+The regular target shape is:
+
+```text
+Scope -> Ability -> Capability -> Feature -> Observed Fact
+```
+
+This regular tree is an orientation tool, not a claim that every real repository
+is perfectly tree-shaped. Cross references and same-level references can be
+useful during review, but they are also quality signals: frequent same-level
+feature references may indicate that features are too coarse, too fine, or
+organized under the wrong capability.
+
+## Facts, Source References, And Evidence
+
+Observed facts are deterministic scanner output. They describe what was seen in
+the repository: files, languages, frameworks, routes, tests, documentation,
+provider names, configuration variables, and similar source-linked observations.
+
+Source references point from interpreted claims back to files or facts.
+
+Evidence is support for a characteristic. It is not the same thing as an observed
+fact. Evidence may reference:
+
+- Observed facts.
+- Source files or content chunks.
+- Lower-level characteristics, such as a capability using features as evidence.
+
+Evidence should usually point downward in abstraction. An ability can use
+capabilities or features as support. A capability can use features or facts as
+support. A feature should usually use facts or source references as support, not
+abilities or capabilities.
+
+Same-level evidence references are allowed as review material, but should be
+treated as a possible organization smell.
+
+## Implementation Direction
+
+The current schema still stores evidence on capabilities, with textual
+references and source refs. The next additive schema step should generalize this
+without breaking existing data:
+
+- Add a scope root per repository.
+- Add typed evidence targets: supported characteristic kind/id.
+- Add typed evidence references: fact, source ref, content chunk, or
+  characteristic kind/id.
+- Keep legacy evidence fields until migration/export/search have been updated.
+
+The UI should make this relationship clear by presenting evidence as support
+under the characteristic it supports, not as a peer of features.