reuse-surface/SCOPE.md

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

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/