generated from coulomb/repo-seed
tegwick
40ab8dded0
Some checks failed
ci / validate-registry (push) Has been cancelled
Add federation manifest and schema, federation compose and graph CLI commands, relation cycle/reference checks, federated index and Mermaid graph artifacts, RegistryFederation guide, and CI validation updates.
153 lines
4.8 KiB
Markdown
153 lines
4.8 KiB
Markdown
# 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.
|
||
|
||
## 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
|
||
```
|
||
|
||
Output: `docs/graph/capability-graph.mmd`
|
||
|
||
## 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. |