2.5 KiB
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:
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.