repo-scoping/docs/terminology.md

Repository Scoping Terminology

Repository Scoping turns repositories into reviewable, source-linked orientation maps. The goal is not to infer every possible product story automatically; it is to give humans and trusted agents a durable structure for understanding what a repository is for and how that claim is supported.

Product Identity

• Repository Scoping is the product and UI name.
• repo-scoping is the managed repository slug, Git remote identity, and State Hub repository identity.
• repo_registry, REPO_REGISTRY_, and var/repo-registry.sqlite3 are retained compatibility names in code and local configuration.
• Repository Ability Registry and repo-registry are historical names from before the scope-oriented rename.

Characteristic Model

A characteristic is any curated statement about a repository at one of the main abstraction levels. The preferred orientation is a mostly tree-shaped model:

Scope -> Ability -> Capability -> Feature -> Evidence -> Observed fact

Real repositories are messier than a perfect tree. Evidence may therefore refer to facts or to lower-granularity characteristics. Same-level references are allowed when useful, but they are also signals that the hierarchy may need manual normalization.

Terms

• Scope: the one root characteristic describing what the repository is about and where it is relevant.
• Ability: a high-level useful outcome the repository can provide.
• Capability: a more concrete thing the repository can do in support of an ability.
• Feature: a user-facing, API-facing, backend, UI, or operational behavior that contributes to a capability.
• Evidence: a support link for a characteristic. Evidence can point to observed facts or to lower-level characteristics.
• Observed fact: deterministic scanner output such as files, manifests, languages, tests, APIs, routes, commands, or documentation references.
• Candidate: proposed characteristic or evidence from deterministic heuristics or optional LLM assistance. Candidates are review inputs, not registry truth.
• Approved: curated registry truth that appears in ability maps, search, exports, and SCOPE generation.
• Rejected: a candidate judged false or irrelevant. Rejected entries are hidden by default but retained for audit and recovery.
• Classification: a main type plus optional additional attributes that help users filter and orient without forcing every item into a single rigid box.

Extraction Philosophy

Deterministic scanning should remain useful without LLM support. Optional LLM assistance is used as a comparison and acceleration layer: when model-assisted expectations reveal missing concepts, the deterministic scanner and heuristics should be improved over time. This creates a feedback loop where repository inspection, manual curation, and optional model output co-evolve.