generated from coulomb/repo-seed
Complete REUSE-WP-0003: registry CLI, docs alignment, and coverage
Align INTENT.md with delivered layout, add CapabilityRegistryConcept guide, extend schema with promotion_history, ship reuse-surface validate/query/export CLI, register three more helix_forge capabilities, and refresh SCOPE and gap analysis to reflect A3 tooling and D5/A3/C4/R2 self-assessment.
This commit is contained in:
129
docs/CapabilityRegistryConcept.md
Normal file
129
docs/CapabilityRegistryConcept.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# Capability Registry Concept
|
||||
|
||||
**Repository:** `reuse-surface`
|
||||
**Audience:** Humans onboarding to the registry
|
||||
**Companion docs:** `INTENT.md`, `SCOPE.md`, `specs/CapabilityMaturityStandard.md`
|
||||
|
||||
---
|
||||
|
||||
## 1. What problem this solves
|
||||
|
||||
Reusable capabilities are often scattered across repositories, documents,
|
||||
prototypes, and services. Without a registry, teams and agents rediscover,
|
||||
duplicate, and inconsistently assess the same behaviors.
|
||||
|
||||
`reuse-surface` makes capabilities **visible**, **comparable**, and **reusable**
|
||||
for planning and implementation through a registry-first reuse layer.
|
||||
|
||||
> A capability that is not registered is invisible for registry-driven reuse.
|
||||
|
||||
---
|
||||
|
||||
## 2. Core principles
|
||||
|
||||
### Registry first
|
||||
|
||||
The registry is the boundary of practical reuse awareness. Analysis starts with
|
||||
what is registered, not with everything that might exist informally.
|
||||
|
||||
### Reuse over inventory
|
||||
|
||||
The goal is capability reuse, not a complete inventory of all work products.
|
||||
|
||||
### Planning and implementation are different
|
||||
|
||||
- **Planning reuse** feeds primarily on **Discovery** maturity (D0–D7).
|
||||
- **Implementation reuse** feeds primarily on **Availability** maturity (A0–A7).
|
||||
|
||||
A capability may be well researched (D5) but only informational (A0). Another
|
||||
may be deployable (A4) but weakly bounded (D2). Compare both dimensions.
|
||||
|
||||
### Internal and external evidence stay separate
|
||||
|
||||
| Type | Dimensions | Question |
|
||||
|---|---|---|
|
||||
| Internal registry assessment | Discovery, Availability | How reusable is it for planning? How consumable is it? |
|
||||
| External consumer evidence | Completeness, Reliability | Does scope satisfy intent? Does it behave well in use? |
|
||||
|
||||
Do not treat availability as reliability, or research depth as completeness.
|
||||
|
||||
---
|
||||
|
||||
## 3. Maturity vector
|
||||
|
||||
A compact summary:
|
||||
|
||||
```text
|
||||
D5 / A4 / C3 / R3
|
||||
```
|
||||
|
||||
Vectors are descriptive, not grades. A research vocabulary capability may
|
||||
naturally target `D5 / A0 / C4 / R3`. A CLI tool may target `D5 / A3 / C5 / R5`.
|
||||
|
||||
Canonical level definitions: `specs/CapabilityMaturityStandard.md`.
|
||||
|
||||
---
|
||||
|
||||
## 4. How the artifacts fit together
|
||||
|
||||
```text
|
||||
templates/capability-entry.template.md → authoring starting point
|
||||
registry/capabilities/*.md → canonical entries (YAML front matter)
|
||||
registry/indexes/capabilities.yaml → fast discovery index for agents
|
||||
schemas/capability.schema.yaml → machine-readable entry contract
|
||||
registry/README.md → validation and search guidance
|
||||
tools/ → CLI validate, query, export
|
||||
```
|
||||
|
||||
**Authoring flow**
|
||||
|
||||
1. Search the index for overlap.
|
||||
2. Copy the template to `registry/capabilities/`.
|
||||
3. Fill maturity and evidence fields explicitly.
|
||||
4. Add an index row.
|
||||
5. Validate with `reuse-surface validate`.
|
||||
|
||||
**Consumption flow**
|
||||
|
||||
1. Read `registry/indexes/capabilities.yaml`.
|
||||
2. Filter by vector, tags, or consumption mode.
|
||||
3. Open candidate entry files for scope, relations, and guidance.
|
||||
4. Prefer planning reuse at D3+ and implementation reuse at A2+.
|
||||
|
||||
---
|
||||
|
||||
## 5. What is manual vs automated today
|
||||
|
||||
See `SCOPE.md` for the live boundary. In summary:
|
||||
|
||||
| Activity | Mode |
|
||||
|---|---|
|
||||
| Discover capabilities | Index + `reuse-surface query` |
|
||||
| Add or promote entries | Markdown authoring + index update |
|
||||
| Validate shape | `reuse-surface validate` |
|
||||
| Export for agents | `reuse-surface export` |
|
||||
| Promotion history | Optional `promotion_history` in entries |
|
||||
| Graph visualization, federation, CI gates | Not yet available |
|
||||
|
||||
---
|
||||
|
||||
## 6. When to register a capability
|
||||
|
||||
Register when a bounded reusable behavior should be:
|
||||
|
||||
- discoverable for roadmap or architecture planning
|
||||
- comparable to adjacent capabilities
|
||||
- consumable through known artifacts (now or later)
|
||||
- assessed with explicit evidence over time
|
||||
|
||||
Do not register one-off features, tickets, or internal code modules unless they
|
||||
represent a reusable capability boundary.
|
||||
|
||||
---
|
||||
|
||||
## 7. Further reading
|
||||
|
||||
- Product requirements: `specs/ProductRequirementsDocument.md`
|
||||
- Use cases: `specs/UseCaseCatalog.md`
|
||||
- Intent vs delivered scope: `docs/IntentScopeGapAnalysis.md`
|
||||
- Agent workflows: `AGENTS.md`
|
||||
@@ -13,25 +13,21 @@ current delivered scope so future workplans can close them deliberately.
|
||||
|
||||
`INTENT.md` describes the long-term capability registry product: a reuse surface
|
||||
that makes capabilities visible, assessable, and consumable across planning and
|
||||
implementation. `SCOPE.md` describes what the repository actually delivers today:
|
||||
an MVP registry foundation at **A0 availability** with manual, Markdown-first
|
||||
workflows.
|
||||
implementation. `SCOPE.md` describes what the repository actually delivers today: an MVP registry
|
||||
with **A3 CLI tooling** (`validate`, `query`, `export`) atop Markdown-first
|
||||
authoring.
|
||||
|
||||
The two documents are **directionally aligned** on registry-first reuse, four
|
||||
maturity dimensions, and human/agent consumers. The main gaps are:
|
||||
maturity dimensions, and human/agent consumers. REUSE-WP-0003 closed the
|
||||
priority gaps from section 8. Remaining gaps are primarily scale, automation,
|
||||
and presentation concerns:
|
||||
|
||||
1. **Delivery depth** — INTENT promises eventual technical foundation and broad
|
||||
planning/implementation support; SCOPE delivers informational tooling only.
|
||||
2. **Structural drift** — INTENT's expected repository layout and entry shape
|
||||
differ from the implemented layout and schema in small but important ways.
|
||||
3. **Evidence and operations** — INTENT emphasizes consumer evidence and
|
||||
progress tracking; SCOPE has no reliability evidence, promotion history, or
|
||||
automated validation yet.
|
||||
4. **Document cross-coverage** — SCOPE operationalizes State Hub, MVP acceptance
|
||||
criteria, and helix_forge domain context that INTENT does not mention; INTENT
|
||||
carries success criteria and conceptual depth that SCOPE does not restate.
|
||||
1. **Planning analytics** — no gap reports, overlap detection, or catalog site.
|
||||
2. **Reliability depth** — registry product dogfood evidence is early (R2).
|
||||
3. **Document cross-coverage** — SCOPE still carries operational detail INTENT
|
||||
omits; INTENT success criteria are not fully enumerated in SCOPE.
|
||||
|
||||
**Current reuse-surface vector (self-assessment):** `D4 / A0 / C3 / R0`
|
||||
**Current reuse-surface vector (self-assessment):** `D5 / A3 / C4 / R2`
|
||||
|
||||
---
|
||||
|
||||
@@ -256,18 +252,25 @@ own evidence (e.g. feature-control at R3).
|
||||
|
||||
## 8. Priority Gap Closure Order
|
||||
|
||||
Recommended sequence for future workplans:
|
||||
| Priority | Gap | Outcome | Status |
|
||||
|---|---|---|---|
|
||||
| 1 | INTENT layout stale | INTENT layout aligned to delivered structure | Closed (WP-0003) |
|
||||
| 2 | No automated validation | `reuse-surface validate` | Closed (WP-0003) |
|
||||
| 3 | Thin registry coverage | Six helix_forge entries | Closed (WP-0003) |
|
||||
| 4 | Missing concept docs | `docs/CapabilityRegistryConcept.md` | Closed (WP-0003) |
|
||||
| 5 | No promotion history | `promotion_history` in schema/template | Closed (WP-0003) |
|
||||
| 6 | Search/filter manual only | `reuse-surface query` | Closed (WP-0003) |
|
||||
| 7 | No registry export | `reuse-surface export` | Closed (WP-0003) |
|
||||
| 8 | Self-reliability evidence | `capability.registry.register` at R2; friction recorded | Closed (WP-0003) |
|
||||
|
||||
### Next recommended work
|
||||
|
||||
| Priority | Gap | Suggested outcome |
|
||||
|---|---|---|
|
||||
| 1 | INTENT layout stale | Update INTENT "Initial Repository Role" to match `SCOPE.md` layout |
|
||||
| 2 | No automated validation | CLI or script: validate entries against schema |
|
||||
| 3 | Thin registry coverage | Register additional helix_forge capabilities beyond 3 samples |
|
||||
| 4 | Missing concept docs | Add `docs/CapabilityRegistryConcept.md` distilled from INTENT |
|
||||
| 5 | No promotion history | Add `promotion_history` to schema or separate changelog |
|
||||
| 6 | Search/filter manual only | CLI `query` with discovery/availability filters |
|
||||
| 7 | No registry export | YAML/JSON bundle export for agents (UC-RS-019) |
|
||||
| 8 | Self-reliability evidence | Dogfood registry; record friction as reliability evidence |
|
||||
| 9 | Catalog site | Static browsable capability catalog (UC-RS-018) |
|
||||
| 10 | Overlap detection | CLI or report for duplicate/overlapping capabilities |
|
||||
| 11 | CI validation | Run `reuse-surface validate` in CI on registry changes |
|
||||
| 12 | Registry federation | Cross-repo capability index composition |
|
||||
|
||||
---
|
||||
|
||||
@@ -285,4 +288,5 @@ Recommended sequence for future workplans:
|
||||
|
||||
| Date | Change |
|
||||
|---|---|
|
||||
| 2026-06-15 | Initial analysis after REUSE-WP-0002 completion |
|
||||
| 2026-06-15 | Initial analysis after REUSE-WP-0002 completion |
|
||||
| 2026-06-15 | REUSE-WP-0003 closed priority gaps 1–8; vector updated to D5/A3/C4/R2 |
|
||||
Reference in New Issue
Block a user