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.
• Intent: a design-time statement of expected repository utility. INTENT.md is the preferred file for this. It can guide candidate generation because it describes why the repository should exist.
• Derived scope: a current-state statement of what the repository is understood to provide. SCOPE.md is the preferred file for this. It is generated or curated from evidence and approved characteristics, so it should not be used as ordinary evidence for rebuilding those same characteristics.
• Intent bootstrap: a one-time migration that creates INTENT.md from an existing SCOPE.md when no intent file exists. The generated file carries a provenance note and should be reviewed as design intent.
• Source role: provenance metadata on a fact or content chunk, such as intent_summary, derived_scope, product_documentation, implementation_source, dependency_declaration, configuration, ci_tooling, test_evidence, or agent_guidance.
• Utility relationship: metadata describing how a fact relates to repository utility, such as owned, facade, adapter, configure, dependency, tooling, or mention. Only owned/facade/adapter relationships should be promoted directly into provided capabilities.
• 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.