diff --git a/README.md b/README.md index c2de96a..5bf46a5 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ -# Repository Ability Registry +# Repository Scoping -The Repository Ability Registry maps repositories from usefulness to implementation: +Repository Scoping maps repositories from usefulness to implementation: ```text Ability -> Capability -> Feature -> Evidence -> Code location ``` -The first implementation slice is a Python registry core plus FastAPI HTTP API and a small curator UI. Repository registration imports basic metadata from the repository itself, then analysis builds observed facts and candidate review entries. +The implementation is a Python registry core plus FastAPI HTTP API and a small curator UI. Repository registration imports basic metadata from the repository itself, then analysis builds observed facts and candidate review entries. ## Local Development @@ -30,7 +30,7 @@ Run the API: uvicorn repo_registry.web_api.app:app --reload ``` -The API creates a local SQLite database at `var/repo-registry.sqlite3` by default. +The API creates a local SQLite database at `var/repo-registry.sqlite3` by default. The database path, `REPO_REGISTRY_` environment prefix, and `repo_registry` Python package name remain compatibility details after the product rename to Repository Scoping. ## First API Loop diff --git a/SCOPE.md b/SCOPE.md index 2eaa774..216ade0 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -1,7 +1,7 @@ --- domain: capabilities repo: repo-scoping -updated: "2026-04-30" +updated: "2026-05-01" --- # SCOPE @@ -169,7 +169,7 @@ keywords: [scope, scope-md, update, diff, staleness] ## Notes -- 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. +- 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. diff --git a/docs/abstraction-strategy.md b/docs/abstraction-strategy.md index 08fd611..0f2e237 100644 --- a/docs/abstraction-strategy.md +++ b/docs/abstraction-strategy.md @@ -55,7 +55,7 @@ truth. ## Trial Repo Observations -`repo-registry` demonstrates the current boundary well: deterministic scanning sees +`repo-scoping` demonstrates the current boundary well: deterministic scanning sees FastAPI routes, tests, docs, and Python structure, but the meaningful abstractions are repository ingestion, deterministic analysis, candidate review, discovery, and State Hub coordination. Those names likely require either review edits or LLM diff --git a/docs/classification-strategy.md b/docs/classification-strategy.md index 362be62..f409296 100644 --- a/docs/classification-strategy.md +++ b/docs/classification-strategy.md @@ -1,6 +1,6 @@ # Classification Strategy -Repo-registry needs classification for orientation without pretending repository +Repo-scoping needs classification for orientation without pretending repository behavior is always cleanly separable. The review UI should therefore support two layers of classification: diff --git a/docs/operations.md b/docs/operations.md index 30d5b23..d71358b 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -1,12 +1,13 @@ # Operational Readiness This note captures the runtime knobs and baseline operating procedures for the -Repository Ability Registry service. +Repository Scoping service. ## Configuration Configuration is read from environment variables with the `REPO_REGISTRY_` -prefix. +prefix. That prefix is retained as an implementation compatibility detail after +the product rename from Repository Ability Registry to Repository Scoping. | Variable | Default | Purpose | | --- | --- | --- | diff --git a/docs/scope-md-spec.md b/docs/scope-md-spec.md index 6e2c177..d7f44ed 100644 --- a/docs/scope-md-spec.md +++ b/docs/scope-md-spec.md @@ -4,7 +4,7 @@ It answers, quickly and concretely, what the repository is for, when it is useful, where it fits, and what capabilities it can provide. -Repo-registry is the source of truth for generating and validating `SCOPE.md` +Repo-scoping is the source of truth for generating and validating `SCOPE.md` because its approved characteristic model already captures the same structure: ```text @@ -14,7 +14,7 @@ Scope -> Ability -> Capability -> Feature -> Evidence -> Observed Fact This specification supersedes the Custodian dashboard reference at `state-hub/dashboard/src/docs/scope.md`. The scaffold template remains at `state-hub/scripts/project_rules/scope.template`; this document defines how -repo-registry should generate, validate, and update that file. +repo-scoping should generate, validate, and update that file. Related model docs: @@ -41,12 +41,12 @@ It should answer: The historical Custodian reference calls this an "11-section template". The current `scope.template` contains twelve functional sections plus an optional -`Notes` tail. Repo-registry should preserve the current template headings for +`Notes` tail. Repo-scoping should preserve the current template headings for compatibility and treat `Notes` as curator-owned free text. Generated files must contain these sections, in this order: -| Section | Source in repo-registry | Generation ownership | +| Section | Source in repo-scoping | Generation ownership | |---------|--------------------------|----------------------| | `## One-liner` | Scope name plus scope description | generated, curator-reviewed | | `## Core Idea` | Scope description and top approved abilities | generated, curator-reviewed | @@ -101,7 +101,7 @@ Suggested form: ### Out of Scope -This section is primarily curator-owned. Repo-registry may seed it from +This section is primarily curator-owned. Repo-scoping may seed it from classification expectation gaps whose `expected_type` is one of: - `classification-granularity` @@ -225,7 +225,7 @@ requested. ## Generation Ownership -Repo-registry-generated sections: +Repo-scoping-generated sections: - One-liner - Core Idea @@ -258,7 +258,7 @@ The validator should mirror the Custodian DOI C5 checks: - C5c: `## Provided Capabilities` contains parseable `capability` blocks, or an explicit empty-state note when the repo provides no routable capabilities. -Additional repo-registry validation: +Additional repo-scoping validation: - Generated sections with missing data must include ``. - Capability blocks must parse as key/value metadata. diff --git a/docs/terminology.md b/docs/terminology.md new file mode 100644 index 0000000..f692e99 --- /dev/null +++ b/docs/terminology.md @@ -0,0 +1,60 @@ +# 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. +- 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. diff --git a/pyproject.toml b/pyproject.toml index c0ab035..e4c4078 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta" [project] name = "repo-registry" version = "0.1.0" -description = "Repository Ability Registry" +description = "Repository Scoping" readme = "README.md" requires-python = ">=3.12" dependencies = [ diff --git a/src/repo_registry/__init__.py b/src/repo_registry/__init__.py index 8add065..7b0faae 100644 --- a/src/repo_registry/__init__.py +++ b/src/repo_registry/__init__.py @@ -1,4 +1,4 @@ -"""Repository Ability Registry.""" +"""Repository Scoping.""" __all__ = ["__version__"] diff --git a/src/repo_registry/scope/generator.py b/src/repo_registry/scope/generator.py index d52d9b8..084d349 100644 --- a/src/repo_registry/scope/generator.py +++ b/src/repo_registry/scope/generator.py @@ -57,7 +57,7 @@ class ScopeGenerator: "", "> This file helps you quickly understand what this repository is about,", "> when it is relevant, and when it is not.", - "> It was generated from approved repo-registry characteristics.", + "> It was generated from approved repo-scoping characteristics.", "", "---", "", diff --git a/src/repo_registry/web_api/app.py b/src/repo_registry/web_api/app.py index ac609e9..e2c8f8a 100644 --- a/src/repo_registry/web_api/app.py +++ b/src/repo_registry/web_api/app.py @@ -113,7 +113,7 @@ def get_service(settings: Settings = Depends(get_settings)) -> RegistryService: API_DESCRIPTION = ( "Register repositories, analyze their observable implementation facts, " - "curate reviewable ability graphs, and search approved repository abilities." + "curate reviewable scope graphs, and search approved repository characteristics." ) OPENAPI_TAGS = [ @@ -128,7 +128,7 @@ OPENAPI_TAGS = [ ] app = FastAPI( - title="Repository Ability Registry", + title="Repository Scoping", version="0.1.0", description=API_DESCRIPTION, openapi_tags=OPENAPI_TAGS, diff --git a/src/repo_registry/web_ui/views.py b/src/repo_registry/web_ui/views.py index 0411aa8..17fec7d 100644 --- a/src/repo_registry/web_ui/views.py +++ b/src/repo_registry/web_ui/views.py @@ -2,6 +2,7 @@ from __future__ import annotations from dataclasses import asdict from html import escape +from pathlib import Path from urllib.parse import quote_plus from fastapi import APIRouter, Depends, Form, HTTPException, Query @@ -13,6 +14,7 @@ from repo_registry.web_api.app import get_service router = APIRouter(include_in_schema=False) +APP_NAME = "Repository Scoping" def page(title: str, body: str) -> HTMLResponse: @@ -23,7 +25,7 @@ def page(title: str, body: str) -> HTMLResponse: - {escape(title)} · Repository Ability Registry + {escape(title)} · {APP_NAME}