# 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 the manual validation checklist below.

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

## 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.

## 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`.
6. Set `status: reviewed` or `approved` when an assessor validates the entry.