generated from coulomb/repo-seed
Transfered deep scope functionality from the custodian
This commit is contained in:
197
SCOPE.md
197
SCOPE.md
@@ -1,48 +1,175 @@
|
||||
---
|
||||
domain: capabilities
|
||||
repo: repo-registry
|
||||
updated: "2026-04-26"
|
||||
repo: repo-scoping
|
||||
updated: "2026-04-30"
|
||||
---
|
||||
|
||||
# repo-registry — Scope
|
||||
# SCOPE
|
||||
|
||||
## Purpose
|
||||
> 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.
|
||||
|
||||
Repository Ability Registry. Turns Git repositories into reviewable, source-linked
|
||||
maps of `Ability → Capability → Feature → Evidence`.
|
||||
---
|
||||
|
||||
## Core Design Principle
|
||||
## One-liner
|
||||
|
||||
```
|
||||
deterministic scanners → observed facts (file paths, languages, API routes, …)
|
||||
LLM-assisted extractors → interpreted claims (ability names, descriptions, links)
|
||||
human / agent review → approved registry truth
|
||||
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 Repositories
|
||||
|
||||
- `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
|
||||
|
||||
```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]
|
||||
```
|
||||
|
||||
Approved entries are always explicit, reviewable, and source-linked. The system
|
||||
never publishes unapproved claims as canonical truth.
|
||||
```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]
|
||||
```
|
||||
|
||||
## In Scope (v0.1)
|
||||
---
|
||||
|
||||
- Repository registration by Git URL
|
||||
- Deterministic repository scan (file tree, languages, frameworks, API/CLI surface)
|
||||
- Candidate extraction for abilities, capabilities, features, and evidence
|
||||
- Human review workflow: edit, approve, reject, merge, relink
|
||||
- Natural-language and semantic search over approved registry entries
|
||||
- REST API for repositories, ability maps, capabilities, and search
|
||||
## Notes
|
||||
|
||||
## Out of Scope (v0.1)
|
||||
|
||||
- Continuous GitHub App integration
|
||||
- Full static code understanding (AST/type analysis)
|
||||
- Advanced ontology enforcement
|
||||
- Distributed indexing
|
||||
- Benchmark execution
|
||||
- Marketplace or commercial features
|
||||
- Complex access control
|
||||
- Automated truth claims without review
|
||||
|
||||
## Domain Context
|
||||
|
||||
Part of the **capabilities** domain — systematic modeling of abilities, capabilities,
|
||||
and features across the Custodian ecosystem. First registered repo in this domain.
|
||||
- The local checkout path is still `/home/worsch/repo-registry`; the canonical
|
||||
State Hub slug and Git remote are now `repo-scoping`.
|
||||
- Ecosystem-wide SCOPE.md refresh is blocked until Custodian C5b/C5c checks are
|
||||
active and more managed repos have approved characteristics in repo-scoping.
|
||||
|
||||
Reference in New Issue
Block a user