# INTENT.md — reuse-surface

## Project Name

`reuse-surface`

## One-Line Intent

`reuse-surface` provides a registry-centric capability reuse surface that makes capabilities visible, comparable, assessable, and reusable for planning, implementation, and operation.

## Purpose

The purpose of `reuse-surface` is to turn scattered capabilities into inspectable reuse assets.

A capability that is not registered is effectively invisible for reuse. `reuse-surface` therefore treats registry membership as the boundary of relevance: once a capability is present in the registry, it can be discovered, assessed, compared, planned with, implemented against, improved, and eventually standardized.

The project exists to answer four practical questions:

1. **What capabilities do we have or intend to have?**
2. **How mature are they for planning reuse?**
3. **How available are they for implementation or operational reuse?**
4. **How well do consumers experience them in terms of completeness and reliability?**

## Core Idea

`reuse-surface` is not merely a catalog of features or services. It is a structured reuse layer for capabilities.

A capability describes a bounded behavior or power that can be reused across products, repositories, systems, agents, workflows, or organizations. Features may expose capabilities. Services may deliver capabilities. Products may bundle capabilities. But the registry focuses on the reusable capability itself.

The central assumption is:

> A capability registry should not primarily describe what exists. It should describe what can be reused, at which confidence level, for which kind of work.

## Scope

`reuse-surface` shall provide the conceptual, structural, and eventually technical foundation for a capability registry.

In scope:

- capability registration
- capability identity and naming
- capability descriptions and boundaries
- discovery maturity assessment
- availability maturity assessment
- completeness assessment based on SCOPE vs INTENT and consumer expectations
- reliability assessment based on consumer-relevant quality signals
- relationships between capabilities
- evidence references for maturity claims
- registry formats usable by humans and agents
- planning support for prototype, MVP, enhancement, and platform decisions
- implementation support through discoverable consumption modes

Out of scope for the initial intent:

- judging internal code quality as capability maturity
- replacing feature maturity, service maturity, or operational maturity models
- enforcing one specific implementation architecture
- requiring all capabilities to become services or products
- treating unregistered capabilities as relevant for reuse analysis

## Capability Maturity Dimensions

`reuse-surface` uses four complementary dimensions.

### Internal Registry Assessments

These dimensions are assessed from the registry perspective.

#### Discovery Maturity

Discovery maturity measures how reusable the capability is for planning, orientation, comparison, roadmap design, and architectural reasoning.

Canonical levels:

- **D0 Named** — capability is visible in the registry.
- **D1 Described** — capability has meaning, intent, and context.
- **D2 Bounded** — scope, inclusions, exclusions, and neighboring capabilities are defined.
- **D3 Explored** — obvious relevant aspects have been investigated.
- **D4 Researched** — prior art, alternatives, products, standards, and tradeoffs have been deeply examined.
- **D5 Grounded** — concrete use cases, actors, scenarios, and prioritization criteria are documented.
- **D6 Exhaustive** — use-case and scope exploration has likely reached saturation.
- **D7 Generalized** — the capability has become a reusable planning primitive beyond one repo, product, or domain.

#### Availability Maturity

Availability maturity measures how directly the capability can be consumed for implementation or operation.

Canonical levels:

- **A0 Informational Only** — read and plan only.
- **A1 Experimental Prototype** — learn and experiment.
- **A2 Source Module / Library** — import and build with code.
- **A3 Command-Line Package** — automate via CLI.
- **A4 Service API / SDK** — integrate into applications.
- **A5 Containerized Service** — deploy and operate.
- **A6 Managed Platform Capability** — consume as an internal platform service.
- **A7 External Cloud Service Offering** — consume as a public or commercial cloud/API service.

### External Consumer Evidence

These dimensions are derived from consumer experience and evidence.

#### Completeness

Completeness measures how well current SCOPE satisfies declared INTENT and consumer expectations.

Canonical levels:

- **C0 Unknown** — no meaningful evidence.
- **C1 Fragmentary** — isolated parts of the expected capability are present.
- **C2 Partial** — some important expectations are satisfied, but major gaps remain.
- **C3 Functional Core** — the central expected use case works.
- **C4 Broadly Covered** — most common expectations are satisfied; gaps are known and bounded.
- **C5 Expectation Complete** — declared intent is substantially fulfilled for known expectations.
- **C6 Saturated** — further consumer discovery rarely reveals missing scope.

#### Reliability

Reliability measures how consistently the capability satisfies consumer-relevant quality expectations in real or realistic use.

Canonical levels:

- **R0 Unknown** — no meaningful evidence.
- **R1 Fragile** — frequently breaks, surprises, or disappoints consumers.
- **R2 Tolerable** — works in selected situations, but consumers must expect friction.
- **R3 Usable** — works reliably for normal use with known limitations.
- **R4 Dependable** — consumers can rely on it for important workflows.
- **R5 Trusted** — strong consumer confidence; failures are rare and well handled.
- **R6 Proven** — reliability is demonstrated across broad, repeated, and demanding use.

## Capability Vector

A registered capability may be summarized with a compact vector:

```text
D5 / A4 / C3 / R3
```

Meaning:

- discovery maturity: grounded
- availability maturity: service API / SDK
- completeness: functional core
- reliability: usable

The vector is descriptive, not a moral grade. Different capability types may have different target vectors.

For example:

- a research method may naturally target `D5 / A0 / C4 / R3`
- a CLI tool may naturally target `D5 / A3 / C5 / R5`
- an internal platform service may naturally target `D6 / A6 / C5 / R5`
- a commercial API offering may naturally target `D7 / A7 / C6 / R6`

## Guiding Principles

### Registry First

Capabilities outside the registry are invisible for reuse analysis. The registry is the reuse surface.

### Reuse Over Inventory

The registry should optimize for capability reuse, not merely inventory completeness.

### Planning and Implementation Are Different

Planning reuse feeds primarily on discovery maturity. Implementation reuse feeds primarily on availability maturity.

### Internal and External Evidence Must Stay Separate

Discovery and availability are internal registry assessments. Completeness and reliability are external consumer-evidence dimensions.

### Capability Maturity Is Not Feature Maturity

Internal code structure, UI polish, local implementation elegance, and feature detail quality may matter, but they are not the same as capability maturity. They can be assessed separately when needed.

### SCOPE vs INTENT Matters

Completeness depends on the relationship between declared intent, current scope, and consumer expectations. Broken expectations are first-class evidence.

### Consumer Experience Matters

Reliability depends on consumer-relevant evidence such as bug reports, support tickets, incidents, failed integrations, ratings, adoption, retention, and qualitative feedback.

### Target Maturity Should Be Explicit

Not every capability needs to become a cloud service. Each capability should have a current vector and, where useful, a target vector.

## Expected Registry Entry Shape

A registry entry should eventually support a structure similar to:

```yaml
id: capability.example
name: Example Capability
summary: Short capability summary.

maturity:
  discovery:
    current: D2
    target: D5
  availability:
    current: A1
    target: A4

external_evidence:
  completeness:
    level: C1
    confidence: low
  reliability:
    level: R0
    confidence: low

discovery:
  intent: What this capability is meant to make possible.
  includes: []
  excludes: []
  assumptions: []
  use_cases: []
  research_memos: []

availability:
  current_artifacts: []
  target_artifacts: []
  consumption_modes: []

relations:
  depends_on: []
  supports: []
  related_to: []

evidence:
  documentation: []
  tests: []
  consumer_feedback: []
  bug_reports: []
  incidents: []
```

## Initial Repository Role

The initial role of `reuse-surface` is to define and maintain the capability
registry model, standards, schemas, examples, reference tooling, and federation
hub coordinator.

Current repository layout (authoritative for delivery — see `SCOPE.md` for detail):

```text
reuse-surface/
├── INTENT.md
├── SCOPE.md
├── AGENTS.md
├── pyproject.toml
├── Dockerfile
├── reuse_surface/          # CLI, hub service, federation, graph, catalog
├── specs/
│   ├── ProductRequirementsDocument.md
│   ├── UseCaseCatalog.md
│   ├── CapabilityMaturityStandard.md
│   └── FederationHubAPI.md
├── schemas/
│   ├── capability.schema.yaml
│   ├── federation.schema.yaml
│   └── hub-registration.schema.yaml
├── templates/
│   └── capability-entry.template.md
├── registry/
│   ├── README.md
│   ├── capabilities/       # per-entry Markdown
│   ├── indexes/            # capabilities.yaml, federated.yaml
│   └── federation/         # sources.yaml, cache/
├── docs/
│   ├── CapabilityRegistryConcept.md
│   ├── RegistryFederation.md
│   ├── IntentScopeGapAnalysis.md
│   ├── deploy/reuse-kubernetes.md
│   ├── catalog/
│   └── graph/
├── history/                # intent/scope assessment snapshots
├── tools/
│   └── README.md
└── workplans/
    └── archived/
```

See `SCOPE.md` for what is possible now versus planned. See
`docs/IntentScopeGapAnalysis.md` for tracked gaps between intent and delivered
scope. Federation operations: `docs/RegistryFederation.md` and
`specs/FederationHubAPI.md`. Assessment history:
`history/2026-06-15-intent-scope-assessment.md`.

## Success Criteria

`reuse-surface` is successful when it helps humans and agents:

- find reusable capabilities before rebuilding them
- compare capability maturity consistently
- distinguish conceptual readiness from delivery availability
- distinguish internal registry assessment from external consumer evidence
- plan prototype, MVP, enhancement, and platform work more effectively
- identify capability gaps, duplicates, overlaps, and standardization candidates
- track progress from named ideas to generalized reusable capabilities
- make capability reuse a normal part of product and architecture work

## Non-Goals

`reuse-surface` is not intended to become:

- a generic feature tracker
- a project management replacement
- a service catalog only
- a CMDB only
- an implementation quality gate by itself
- a forced architecture pattern
- a claim that all reusable things must be services

## Working Mantra

> Make capabilities visible enough to plan with, available enough to build with, and evidenced enough to trust.