repo-scoping/SCOPE.md

---
domain: capabilities
repo: repo-scoping
updated: "2026-05-01"
---

# SCOPE

> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
> It is curated from repo-scoping's approved characteristics and operating role.

---

## One-liner

repo-scoping turns Git repositories into reviewable, source-linked scope maps and
maintains SCOPE.md files as the human and agent entry point to repository utility.

---

## Core Idea

repo-scoping models a repository as a hierarchy of characteristics:
`Scope -> Ability -> Capability -> Feature -> Evidence -> Observed Fact`.

Deterministic scanners establish observed facts from repository content. Optional
LLM-assisted extraction proposes interpreted candidates. Humans or trusted agents
approve the resulting characteristics before they become registry truth.

The primary output is a useful repository scope profile: what a repo is for, when
to use it, what capabilities it provides, and which facts or lower-level
characteristics support those claims.

---

## In Scope

- Register repositories and keep metadata, analysis runs, facts, candidates, and
  approved characteristics together.
- Analyze repositories with deterministic scanners and optional LLM-assisted
  candidate extraction.
- Review, edit, approve, reject, merge, and relink candidate abilities,
  capabilities, features, and evidence.
- Search and compare approved repository characteristics.
- Generate, diff, validate, and write SCOPE.md files from approved
  characteristics.
- Support the Custodian State Hub by acting as the provider for scope generation
  and update capabilities.

---

## Out of Scope

- Owning the Custodian State Hub, its database, or cross-domain governance rules.
- Making unreviewed truth claims canonical without approval.
- Replacing human product judgment for curator-owned scope sections.
- Continuous Git hosting automation, deployment infrastructure, or access-control
  policy beyond repository ingestion needs.
- Full static code understanding across every language and framework.

---

## Relevant When

- You need to understand what a repository is useful for without reading the whole
  codebase first.
- You want a source-linked map from high-level repository scope down to observed
  implementation facts.
- You need to review generated candidate abilities, capabilities, features, and
  evidence before approving them.
- You need to create or refresh a SCOPE.md for a registered repository.
- You need to compare repositories by approved characteristics or find capability
  gaps across a domain.

---

## Not Relevant When

- You only need raw Git hosting, CI, deployment, or issue tracking.
- You need a fully autonomous ontology without human review.
- The repository has not been registered or analyzed and no approved
  characteristics exist yet.
- The needed decision is curator-owned product positioning rather than
  source-observable repository behavior.

---

## Current State

- Status: active and evolving.
- Implementation: FastAPI service with SQLite development storage, deterministic
  Git scanning, candidate graph review workflow, search, comparison, and SCOPE.md
  generation endpoints.
- LLM assistance: optional; deterministic non-LLM behavior remains a first-class
  path for continued optimization.
- UI: available for repository registration, analysis runs, candidate review, and
  characteristic navigation.
- Integration: registered in the Custodian State Hub as `repo-scoping`.

---

## How It Fits

- Upstream coordination: the Custodian State Hub owns workstream/task state,
  managed repository records, and capability routing.
- Downstream consumers: Custodian agents and humans use repo-scoping to inspect,
  refine, and refresh repository utility profiles.
- Often used with: `llm-connect` for optional LLM-assisted extraction and
  `the-custodian` for state, routing, and domain coordination.

---

## Terminology

- Preferred terms: scope, ability, capability, feature, evidence, observed fact,
  characteristic, candidate, approved characteristic, SCOPE.md.
- Also known as: repository scoping service, repository ability registry.
- Potentially confusing terms: evidence is not just a raw fact; it is support for
  a characteristic and may reference facts or lower-level characteristics.
  Candidates are proposed claims awaiting review; approved characteristics are
  canonical registry truth.

---

## Related / Overlapping

- `the-custodian` - coordination layer, State Hub, workplans, and capability
  catalog.
- `llm-connect` - optional provider abstraction for LLM-assisted extraction.
- `markitect` / `markitect-project` - content and documentation platform with
  related scope-document needs.

---

## Getting Oriented

- Start with: `README.md`, `AGENTS.md`, and this `SCOPE.md`.
- Key files / directories: `src/repo_scoping/web_api/app.py`,
  `src/repo_scoping/core/service.py`, `src/repo_scoping/scope/`,
  `src/repo_scoping/candidate_graph/`, `src/repo_scoping/repo_scanning/`,
  `docs/scope-md-spec.md`, and `workplans/`.
- Entry points: `uvicorn repo_scoping.web_api.app:app --reload`, the `/ui`
  routes, and the `/repos/{repo_slug}/scope*` API endpoints.

---

## Provided Capabilities

```capability
type: api
title: scope.generate
description: >
  Generates a SCOPE.md from scratch for a registered repo using its approved
  characteristics profile (abilities, capabilities, features, facts).
keywords: [scope, scope-md, generation, repository-utility]
```

```capability
type: api
title: scope.update
description: >
  Diffs an existing SCOPE.md against the current characteristics profile
  and returns or writes an updated version.
keywords: [scope, scope-md, update, diff, staleness]
```

---

## Notes

- The product and managed repository identity are Repository Scoping /
  `repo-scoping`.
- The Python package name `repo_scoping`, `REPO_SCOPING_` environment prefix,
  and default SQLite filename are the current runtime names.