repo-scoping/SCOPE.md

domain, repo, updated

domain	repo	updated
capabilities	repo-scoping	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_registry/web_api/app.py, src/repo_registry/core/service.py, src/repo_registry/scope/, src/repo_registry/candidate_graph/, src/repo_registry/repo_scanning/, docs/scope-md-spec.md, and workplans/.
• Entry points: uvicorn repo_registry.web_api.app:app --reload, the /ui routes, and the /repos/{repo_slug}/scope* API endpoints.

---

Provided Capabilities

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]

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_registry, REPO_REGISTRY_ environment prefix, and default SQLite filename remain compatibility details.