reuse-surface/registry

Capability Registry

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

Layout

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.

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:

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:

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:

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