# 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, 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 documentation review, `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 is in place. Humans and agents can:

- **Discover capabilities** via `registry/indexes/capabilities.yaml`
- **Add a new capability** at D0/A0/C0/R0 using
  `templates/capability-entry.template.md`
- **Promote capabilities** by updating front matter with evidence-backed
  discovery, availability, completeness, and reliability levels
- **Compare candidates** using maturity vectors, scope, relations, and consumer
  guidance in entry files
- **Record expectations** through `external_evidence.completeness` and
  `external_evidence.reliability` fields
- **Validate entries manually** using the checklist in `registry/README.md`
  against `schemas/capability.schema.yaml`
- **Avoid duplicates** by searching the index before creating new entries

These workflows satisfy the MVP acceptance criteria in
`specs/ProductRequirementsDocument.md` section 16 through manual, Git-friendly
authoring. There is no CLI, API, or automated validator yet.

## What Is Not Possible Yet

- Automated schema validation or registry export
- CLI query/filter commands
- Generated human-readable catalog site
- Capability graph visualization
- Promotion history tracking or review workflows in tooling
- Federation across repositories or organizations

See `tools/README.md` for planned tooling that remains out of scope for the
current MVP.

## Current State

- Status: active MVP registry (documentation-only, A0 availability).
- The repository has no package manifest, build system, runtime app, or
  executable test suite. Registry consumption is informational: read, author,
  compare, and plan.
- Three sample capabilities are registered in `registry/capabilities/`:
  - `capability.registry.register` — D3 / A0 / C1 / R0
  - `capability.feature-control.evaluate` — D5 / A4 / C3 / R3
  - `capability.identity.vocabulary-canonicalize` — D4 / A0 / C2 / R0
- `specs/` holds the product requirements, use case catalog, and maturity
  standard. `schemas/`, `templates/`, `registry/`, and `tools/` hold the
  registry authoring and validation surfaces.
- Bootstrap work (`REUSE-WP-0001`) and MVP registry foundation
  (`REUSE-WP-0002`) are finished. The next work should expand registry coverage,
  tighten validation, or add CLI tooling through new workplans.

## Repository Layout

```text
reuse-surface/
├── INTENT.md
├── SCOPE.md
├── AGENTS.md
├── specs/
│   ├── ProductRequirementsDocument.md
│   ├── UseCaseCatalog.md
│   └── CapabilityMaturityStandard.md
├── schemas/
│   └── capability.schema.yaml
├── templates/
│   └── capability-entry.template.md
├── registry/
│   ├── README.md
│   ├── capabilities/
│   └── indexes/
│       └── capabilities.yaml
├── tools/
│   └── README.md
└── workplans/
```

## Getting Oriented

- Start with: INTENT.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
- Agent instructions: AGENTS.md
- Workplans: workplans/