reuse-surface/registry/README.md

# Capability Registry

Markdown-first registry for reusable capabilities in the helix_forge domain.

## Layout

```text
registry/
├── README.md
├── capabilities/
│   └── capability.<domain>.<name>.md
└── indexes/
    └── capabilities.yaml
```

- **Entries** live in `capabilities/` as Markdown files with YAML front matter.
- **Index** at `indexes/capabilities.yaml` is the fast discovery surface for
  humans and agents.
- **Schema** at `schemas/capability.schema.yaml` defines required front matter.
- **Template** at `templates/capability-entry.template.md` is the authoring
  starting point.

## Add a new capability (D0/A0/C0/R0)

1. Copy `templates/capability-entry.template.md` to
   `registry/capabilities/capability.<domain>.<name>.md`.
2. Set `id`, `name`, `summary`, `owner`, and `status: draft`.
3. Initialize all four dimensions explicitly:
   - `maturity.discovery.current: D0`
   - `maturity.availability.current: A0`
   - `external_evidence.completeness.level: C0`
   - `external_evidence.reliability.level: R0`
4. Add the entry to `registry/indexes/capabilities.yaml`.
5. Run `reuse-surface validate --relations` and `reuse-surface federation compose`.

Missing evidence is acceptable in the MVP when it is explicit rather than hidden.

## LLM-assisted discover review checklist

When using `reuse-surface establish --discover` (llm-connect backend):

- [ ] Every proposed `id` follows `capability.<domain>.<name>` and is not a duplicate
- [ ] `summary`, `discovery.intent`, and maturity vectors match repo reality
- [ ] `owner` reflects the delivering repository or team
- [ ] Relations are empty or manually added after human review
- [ ] Run `reuse-surface validate --root <repo>` before merge
- [ ] Run `reuse-surface establish --publish-check` after pushing to `main`

Discover drafts start at low maturity with explicit auto-draft risks in
`known_reliability_risks`. Promote only with evidence per
`specs/CapabilityMaturityStandard.md`.

## Maintain session checklist (REUSE-WP-0016)

After code or doc changes in the owning repo:

```bash
reuse-surface maintain --all --from-git-since origin/main
reuse-surface validate
git add registry/ && git commit -m "registry: maintain session"
git push origin main
```

Automation (CI or pre-commit):

```bash
reuse-surface maintain --all --auto --no-llm
```

With llm-connect for maturity suggestions:

```bash
export LLM_CONNECT_URL=http://127.0.0.1:8080
reuse-surface maintain --all --from-git-since HEAD~5
```

Review every non-deterministic patch before merge; promotions require evidence
citations on disk per `specs/CapabilityMaturityStandard.md`.

## Manual validation checklist

Use this checklist until an automated CLI validator exists.

### Required fields

- [ ] `id` matches `^capability\.[a-z0-9]+(\.[a-z0-9-]+)+$`
- [ ] `name`, `summary`, `owner`, and `status` are present
- [ ] `maturity.discovery` and `maturity.availability` include `current` and `target`
- [ ] `external_evidence.completeness.level` and `external_evidence.reliability.level` are present
- [ ] Completeness and reliability are **not** nested under `maturity`

### Enum checks

Discovery levels: `D0`–`D7`  
Availability levels: `A0`–`A7`  
Completeness levels: `C0`–`C6`  
Reliability levels: `R0`–`R6`  
Entry status: `draft`, `reviewed`, `approved`, `deprecated`  
Confidence: `low`, `medium`, `high`

Definitions live in `specs/CapabilityMaturityStandard.md`.

### Relation checks

- [ ] Every relation target uses a valid capability ID format
- [ ] Referenced capabilities exist in the index or are explicitly marked as external/planned
- [ ] Cycles in `depends_on` are intentional and documented

### Index checks

- [ ] New entry appears in `indexes/capabilities.yaml`
- [ ] `path` points to the correct Markdown file
- [ ] `vector` matches the entry's current maturity levels

## Search and filter guidance

### UC-RS-004 — Search by planning need

1. Run `reuse-surface query --discovery-min D4` or read the index and scan
   `summary`, `tags`, and `vector`.
2. Open candidate entries and review `discovery.intent`, `discovery.use_cases`,
   and `discovery.includes`.
3. Prefer entries with discovery `D3+` for roadmap work and `D5+` for MVP
   selection.

Example filter:

```yaml
discovery:
  minimum: D4
tags:
  - identity
```

### UC-RS-005 — Search by consumption mode

1. Filter the index by `consumption_modes` or availability level.
2. Open entries and inspect `availability.current_artifacts`.
3. Treat `A0` entries as planning-only; require `A2+` for code reuse and `A3+`
   for automation.

Example filter:

```yaml
availability:
  minimum: A3
consumption_modes:
  - cli
```

### UC-RS-006 — Compare capability candidates

Compare vectors side by side and read:

- `discovery.includes` / `discovery.excludes` for overlap
- `external_evidence.completeness` for expectation fit
- `external_evidence.reliability` for consumer risk
- `relations` for dependency and duplication signals

### UC-RS-015 — Detect duplicate or overlapping capabilities

Run `reuse-surface overlaps` for automated candidate detection, then review:

Check for overlap in:

- similar `name` or `summary`
- shared `discovery.includes`
- `relations.related_to` without clear specialization
- duplicate tags and consumption modes with weak boundary differences

When overlap is real, link entries with `relations.related_to`, `specializes`,
or `generalizes` rather than creating silent duplicates.

## Relation graph

Regenerate the Mermaid graph after relation changes:

```bash
reuse-surface graph
reuse-surface graph --check
```

Outputs:

- `docs/graph/capability-graph.mmd` — Mermaid source
- `docs/graph/index.html` — in-browser explorer (also regenerated by `catalog`)

## External evidence checklist (R1 → R3)

Use this when promoting **reliability** from **R1 Fragile** or **R2 Tolerable**
to **R3 Usable** (normal use with known limitations).

### Minimum evidence for R3

- [ ] At least one **repeatable** quality signal (CI gate, smoke test, or
  documented production check) cited under `evidence.tests` or `evidence.documentation`
- [ ] `known_reliability_risks` lists bounded, current limitations (not empty
  unless risks are genuinely absent)
- [ ] At least one `evidence.consumer_feedback` string or resolved-risk note when
  real consumers exist; otherwise document why feedback is not yet available
- [ ] Optional `external_evidence.reliability.evidence.satisfied_signals` for CI
  or smoke-test citations
- [ ] `confidence` is `medium` or `high` when citing CI/production evidence
- [ ] `promotion_history` records the R dimension change with rationale

### Signals that support R3 for registry tooling

- `reuse-surface validate` in CI with `--fail-on-warnings`
- `pytest` coverage for the capability's consumption path
- Production hub smoke (`GET /health`, `GET /v1/federated`) for API-backed flows
- Operator deploy verification documented in `docs/deploy/reuse-kubernetes.md`

R4+ requires broader consumer evidence (incidents, adoption, SLO) per
`specs/CapabilityMaturityStandard.md`.

## Promote a capability

1. Attach evidence appropriate to the target level in
   `specs/CapabilityMaturityStandard.md`.
2. Update `maturity` and/or `external_evidence` with rationale and confidence.
3. Append a `promotion_history` record with `date`, `dimension`, `from`, `to`,
   and `rationale` (optional `author`).
4. Update `availability.current_artifacts` when a new consumption mode appears.
5. Refresh the index `vector` and run `reuse-surface validate --relations`.
6. Run `reuse-surface federation compose` and `reuse-surface graph`.
6. Set `status: reviewed` or `approved` when an assessor validates the entry.