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

```text
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`.
- 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.