Files

tegwick 8889fc3430 Documentation, terminology repo cleanup.

2026-05-01 15:00:39 +02:00

5.9 KiB

Raw Blame History

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.

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.

5.9 KiB Raw Blame History