generated from coulomb/repo-seed
tegwick
270065ff58
Some checks failed
ci / validate-registry (push) Has been cancelled
Add hub sync and report cohorts CLI commands with pytest coverage, document sibling index publish contract and hub hardening path, align INTENT layout, raise external evidence on three registry entries, and close gap priorities 19-23 (priority 18 deferred on sibling index blocks).
199 lines
6.3 KiB
Markdown
199 lines
6.3 KiB
Markdown
---
|
|
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: A4
|
|
target: A5
|
|
confidence: medium
|
|
rationale: >
|
|
Local registry workflows use the reuse-surface CLI (A3). Federation repo
|
|
registration is also available through the hosted hub HTTP API at
|
|
reuse.coulomb.social (POST/PATCH /v1/repos), deployed and dogfood-tested
|
|
on Railiance01 (REUSE-WP-0011).
|
|
|
|
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
|
|
- federation repo registration via hosted hub API and hub CLI
|
|
broken_expectations:
|
|
- no automated duplicate detection yet
|
|
out_of_scope_expectations:
|
|
- hosting registered capabilities
|
|
- enforcing implementation architecture
|
|
reliability:
|
|
level: R3
|
|
name: Usable
|
|
confidence: medium
|
|
basis: consumer_quality_signals
|
|
known_reliability_risks:
|
|
- index drift still possible if authors skip validate
|
|
- CLI requires local venv install
|
|
- sibling repos cannot register until indexes publish raw URLs
|
|
evidence:
|
|
satisfied_signals:
|
|
- CI validate with fail-on-warnings on every push
|
|
- hub register/list/federated smoke on production reuse.coulomb.social
|
|
- pytest coverage for hub API and federation compose paths
|
|
|
|
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: A4
|
|
target_level: A5
|
|
current_artifacts:
|
|
- templates/capability-entry.template.md
|
|
- registry/indexes/capabilities.yaml
|
|
- reuse_surface/cli.py
|
|
- reuse_surface/hub/
|
|
- specs/FederationHubAPI.md
|
|
- https://reuse.coulomb.social
|
|
target_artifacts:
|
|
- packaged container release with documented SLO
|
|
consumption_modes:
|
|
- informational
|
|
- markdown authoring
|
|
- cli
|
|
- service API
|
|
|
|
relations:
|
|
depends_on: []
|
|
supports:
|
|
- capability.feature-control.evaluate
|
|
- capability.identity.vocabulary-canonicalize
|
|
related_to:
|
|
- capability.registry.validate
|
|
|
|
evidence:
|
|
documentation:
|
|
- INTENT.md
|
|
- specs/UseCaseCatalog.md
|
|
- specs/FederationHubAPI.md
|
|
- docs/deploy/reuse-kubernetes.md
|
|
tests:
|
|
- tests/test_hub.py
|
|
- tests/test_hub_sync.py
|
|
- .gitea/workflows/ci.yml
|
|
consumer_feedback:
|
|
- >
|
|
reuse-surface dogfood (REUSE-WP-0011): production hub registration and
|
|
/v1/federated compose succeeded on Railiance01 without write-path
|
|
regressions after WP-0011 deploy.
|
|
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
|
|
- date: "2026-06-15"
|
|
dimension: availability
|
|
from: A3
|
|
to: A4
|
|
rationale: >
|
|
Hosted federation hub live at reuse.coulomb.social; hub register/update
|
|
via HTTP API and reuse-surface hub CLI; production deploy on Railiance01.
|
|
author: reuse-surface
|
|
- date: "2026-06-16"
|
|
dimension: reliability
|
|
from: R2
|
|
to: R3
|
|
rationale: >
|
|
CI gates, pytest hub/federation coverage, and production hub smoke support
|
|
normal registration workflows with documented limitations.
|
|
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
|
|
|
|
**Local registry (A3 CLI):** add Markdown entries under `registry/capabilities/`,
|
|
update `registry/indexes/capabilities.yaml`, run `reuse-surface validate`.
|
|
|
|
**Federation registration (A4 API):** register published index URLs on the hosted
|
|
hub (`reuse-surface hub register`, `POST /v1/repos`) for cross-repo discovery
|
|
via `GET /v1/federated`.
|
|
|
|
## Next promotion steps
|
|
|
|
1. Attach concrete use cases and actors to reach D5.
|
|
2. Package hub as a versioned container release with operator SLO (A5).
|
|
3. Record consumer expectations and broken expectations as external evidence. |