repo-scoping/docs/characteristic-evidence-model.md

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. Facts can carry a source role so generation can separate product evidence from ambient context. Important roles include:

• intent_summary: INTENT.md or equivalent design-intent material describing why the repository should exist and what utility it is meant to provide.
• derived_scope: SCOPE.md or equivalent current-scope material. This is a derived or curated description of what is believed to be true now, not primary evidence for rebuilding the same characteristic model.
• product_documentation: README, docs, specifications, and user-facing guides.
• implementation_source: source code owned by the repository.
• dependency_declaration: manifests, imports, lockfiles, and package metadata.
• configuration, ci_tooling, test_evidence, and agent_guidance.

INTENT.md and SCOPE.md deliberately answer different questions. Intent is a design artifact: what the repository is supposed to become or provide. Scope is a derived current-state artifact: what the repository is understood to provide after evidence and review. A good SCOPE.md is valuable context, but using it as ordinary evidence for generated characteristics creates a circular model. Rebuilds should therefore prefer INTENT.md, product documentation, source, and tests; SCOPE.md should be used as comparison material or explicit bootstrap input only when a curator chooses that mode.

For repositories that already have a useful SCOPE.md but no INTENT.md, repo-scoping can perform a one-time bootstrap by copying the scope text into a new intent file with a clear provenance note. After that bootstrap, the files should diverge naturally: INTENT.md remains design intent, while SCOPE.md remains generated or curated current scope.

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.