---
id: capability.registry.register
name: Capability Registration
summary: Register a new capability so it becomes visible for planning and implementation reuse.
owner: reuse-surface
status: draft
domain: helix_forge
tags:
  - registry
  - governance
  - meta

maturity:
  discovery:
    current: D3
    target: D5
    confidence: medium
    rationale: >
      Core use case UC-RS-001 is documented in specs/UseCaseCatalog.md and the
      registry model is bounded in INTENT.md, but concrete promotion workflows
      are not yet grounded in registry artifacts.
  availability:
    current: A3
    target: A3
    confidence: medium
    rationale: >
      Registration and maintenance are automatable through the reuse-surface CLI
      for validate, query, and export workflows.

external_evidence:
  completeness:
    level: C2
    name: Partial
    confidence: medium
    basis: scope_vs_intent_and_consumer_expectations
    satisfied_expectations:
      - capability IDs can be assigned in registry entries
      - maturity vectors can be recorded at registration time
      - CLI validate, query, and export support registry workflows
      - promotion history can be recorded in entries
    broken_expectations:
      - no automated duplicate detection yet
    out_of_scope_expectations:
      - hosting registered capabilities
      - enforcing implementation architecture
  reliability:
    level: R2
    name: Tolerable
    confidence: medium
    basis: consumer_quality_signals
    known_reliability_risks:
      - index drift still possible if authors skip validate
      - CLI requires local venv install
      - schema ID pattern required a fix during WP-0003 dogfooding

discovery:
  intent: >
    Make a capability candidate visible in the registry so humans and agents can
    discover, assess, compare, and reuse it instead of rebuilding it in isolation.
  includes:
    - stable capability ID assignment
    - initial discovery and availability classification
    - explicit completeness and reliability placeholders
    - evidence and relation references
  excludes:
    - implementing the registered capability
    - certifying implementation quality
    - operating runtime services for registered capabilities
  assumptions:
    - unregistered capabilities are invisible for registry-driven reuse
    - low-maturity entries are acceptable when evidence gaps are explicit
  use_cases:
    - UC-RS-001
  research_memos:
    - specs/UseCaseCatalog.md
    - specs/ProductRequirementsDocument.md

availability:
  current_level: A3
  target_level: A3
  current_artifacts:
    - templates/capability-entry.template.md
    - registry/indexes/capabilities.yaml
    - reuse_surface/cli.py
  target_artifacts: []
  consumption_modes:
    - informational
    - markdown authoring
    - cli

relations:
  depends_on: []
  supports:
    - capability.feature-control.evaluate
    - capability.identity.vocabulary-canonicalize
  related_to:
    - capability.registry.validate

evidence:
  documentation:
    - INTENT.md
    - specs/UseCaseCatalog.md
  tests: []
  consumer_feedback: []
  bug_reports: []
  incidents: []

consumer_guidance:
  recommended_for:
    - making a new capability visible at D0/A0/C0/R0 with minimal friction
    - seeding planning discussions before implementation exists
  not_recommended_for:
    - treating registry presence as proof of implementation readiness
    - skipping explicit evidence for maturity promotion
  known_limitations:
    - manual index updates are required after adding an entry
    - duplicate detection is guidance-only in the MVP

promotion_history:
  - date: "2026-06-14"
    dimension: discovery
    from: D0
    to: D1
    rationale: Added name, summary, and registry-first intent from INTENT.md.
    author: reuse-surface
  - date: "2026-06-15"
    dimension: discovery
    from: D1
    to: D3
    rationale: Bounded scope with UC-RS-001 and MVP registry artifacts in specs/.
    author: reuse-surface
  - date: "2026-06-15"
    dimension: availability
    from: A0
    to: A3
    rationale: reuse-surface CLI shipped validate, query, and export commands.
    author: reuse-surface
---

# Capability Registration

## Overview

Registration is the entry point for reuse visibility. A capability that is not
registered cannot be discovered through the registry surface, even if code or
documentation exists elsewhere.

## Current reuse mode

Humans and agents add Markdown entries under `registry/capabilities/` and update
`registry/indexes/capabilities.yaml`. This is informational reuse (A0): read,
plan, and author entries.

## Next promotion steps

1. Attach concrete use cases and actors to reach D5.
2. Add a CLI validator to reach A3.
3. Record consumer expectations and broken expectations as external evidence.