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, 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
• 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

• Network-based federation or cross-org index sync
• 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).
• Finished workplans: REUSE-WP-0001 through REUSE-WP-0009.
• Self-assessed vector: D5 / A3 / C4 / R3 (see gap analysis).

Repository Layout

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/