# 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.