From 4672ac6edc1fdd898ec61f660a588158cc1c59bf Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 3 May 2026 00:14:37 +0200 Subject: [PATCH] Added INTENT.md --- INTENT.md | 175 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 INTENT.md diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..216ade0 --- /dev/null +++ b/INTENT.md @@ -0,0 +1,175 @@ +--- +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_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] +``` + +```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_registry`, `REPO_REGISTRY_` environment prefix, + and default SQLite filename remain compatibility details.