# SCOPE

## One-liner

Capability registry for planning and implementation reuse based on discovery and delivery maturity.

## Core Idea

`reuse-surface` provides a registry-centric reuse layer for capabilities. It
makes capabilities visible, comparable, assessable, and reusable for planning,
implementation, and operation. A capability that is not registered is invisible
for reuse within this product boundary.

## In Scope

- Maintain the capability maturity model, standards, schemas, registry formats,
  sample entries, indexes, validation guidance, CLI tooling, and agent
  instructions.
- Keep `INTENT.md`, `specs/`, registry artifacts, and State Hub workplans
  aligned on the registry-first reuse boundary.
- Support humans and agents as registry consumers through Markdown-first
  authoring and machine-readable metadata.
- Record decisions, progress, and workplan status through State Hub.
- Verify changes with `reuse-surface validate`, `git diff --check`, and ADR-001
  consistency checks.

## Out of Scope

- Host or operate the registered capabilities themselves.
- Replace package registries, service catalogs, issue trackers, or project
  management systems.
- Judge internal code quality as capability maturity.
- Own unrelated adjacent systems or make irreversible operational decisions
  without human approval.

## What Is Possible Now

The MVP registry foundation plus CLI tooling (REUSE-WP-0003) is in place. Humans
and agents can:

- **Discover capabilities** via `registry/indexes/capabilities.yaml` or
  `reuse-surface query`
- **Add a new capability** at D0/A0/C0/R0 using
  `templates/capability-entry.template.md`
- **Promote capabilities** with evidence, optional `promotion_history`, and index
  vector updates
- **Compare candidates** using maturity vectors, scope, relations, and consumer
  guidance
- **Record expectations** through `external_evidence.completeness` and
  `external_evidence.reliability`
- **Validate entries automatically** with `reuse-surface validate`
- **Export a machine-readable bundle** with `reuse-surface export`
- **Detect overlap candidates** with `reuse-surface overlaps`
- **Generate a human-readable catalog** with `reuse-surface catalog`
- **Browse a searchable catalog** at `docs/catalog/search.html` (client-side
  filter over `registry.json`)
- **Compose federated indexes** with `reuse-surface federation compose`
  (local paths and remote HTTP URLs with cache)
- **Generate relation graphs** with `reuse-surface graph`
- **Explore relations interactively** at `docs/graph/index.html`
- **Avoid duplicates** by querying the index and checking overlaps before adding entries

Registry tooling availability is **A3** (CLI). The registry product itself is
still documentation-first for authoring; consumption combines Markdown entries,
the index, and CLI automation.

## What Is Not Possible Yet

- Live cross-org index sync (polling/webhooks) beyond on-demand HTTP fetch
- Packaged releases beyond local `pip install -e .` and Gitea CI validation

See `tools/README.md` for command reference.

## Current State

- Status: active MVP registry with CLI tooling.
- Twelve helix_forge capabilities are registered in `registry/capabilities/`.
- `reuse-surface` CLI provides `validate`, `query`, and `export` via
  `pyproject.toml` and `reuse_surface/`.
- `docs/CapabilityRegistryConcept.md` and `docs/IntentScopeGapAnalysis.md`
  document onboarding and intent-scope tracking.
- CI validates the registry and composes federation on push/PR.
- Federated index: `registry/indexes/federated.yaml`.
- Relation graph: `docs/graph/capability-graph.mmd` and explorer at
  `docs/graph/index.html`.
- Searchable catalog: `docs/catalog/search.html`.
- Test suite: `tests/` (pytest).
- Remote federation: HTTP URL sources with cache in `registry/federation/cache/`.
- Finished workplans: `REUSE-WP-0001` through `REUSE-WP-0010`.
- **Self-assessed vector:** `D5 / A3 / C4 / R3` (see gap analysis).

## Repository Layout

```text
reuse-surface/
├── INTENT.md
├── SCOPE.md
├── AGENTS.md
├── pyproject.toml
├── reuse_surface/
├── specs/
├── schemas/
├── templates/
├── registry/
├── docs/
├── tools/
└── workplans/
```

## Getting Oriented

- Start with: INTENT.md
- Registry concept: docs/CapabilityRegistryConcept.md
- Intent vs scope gaps: docs/IntentScopeGapAnalysis.md
- Product requirements: specs/ProductRequirementsDocument.md
- Use cases: specs/UseCaseCatalog.md
- Maturity standard: specs/CapabilityMaturityStandard.md
- Registry index: registry/indexes/capabilities.yaml
- Registry guidance: registry/README.md
- Generated catalog: docs/CapabilityCatalog.md
- Searchable catalog: docs/catalog/search.html
- Federation guide: docs/RegistryFederation.md
- Relation graph: docs/graph/capability-graph.mmd
- Graph explorer: docs/graph/index.html
- CLI reference: tools/README.md
- Agent instructions: AGENTS.md
- Workplans: workplans/