generated from coulomb/repo-seed
65 lines
2.5 KiB
Markdown
65 lines
2.5 KiB
Markdown
# 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.
|