Bootstrap and first implementation

registry/README.md

@@ -0,0 +1,136 @@
+# 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. Read `indexes/capabilities.yaml` 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
+
+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. Update `availability.current_artifacts` when a new consumption mode appears.
+4. Refresh the index `vector` and run the validation checklist.
+5. Set `status: reviewed` or `approved` when an assessor validates the entry.