generated from coulomb/repo-seed
tegwick
c366fc4a4e
Some checks failed
ci / validate-registry (push) Has been cancelled
Add Gitea CI workflow for registry validation, reuse-surface overlaps and catalog commands, generated catalog artifacts, and documentation updates closing gap analysis priorities 9-11.
114 lines
4.2 KiB
Markdown
114 lines
4.2 KiB
Markdown
# SCOPE
|
|
|
|
## One-liner
|
|
|
|
Capability registry for planning and implementation reuse based on discovery and delivery maturity.
|
|
|
|
## Core Idea
|
|
|
|
`reuse-surface` provides a registry-centric reuse layer for capabilities. It
|
|
makes capabilities visible, comparable, assessable, and reusable for planning,
|
|
implementation, and operation. A capability that is not registered is invisible
|
|
for reuse within this product boundary.
|
|
|
|
## In Scope
|
|
|
|
- Maintain the capability maturity model, standards, schemas, registry formats,
|
|
sample entries, indexes, validation guidance, CLI tooling, and agent
|
|
instructions.
|
|
- Keep `INTENT.md`, `specs/`, registry artifacts, and State Hub workplans
|
|
aligned on the registry-first reuse boundary.
|
|
- Support humans and agents as registry consumers through Markdown-first
|
|
authoring and machine-readable metadata.
|
|
- Record decisions, progress, and workplan status through State Hub.
|
|
- Verify changes with `reuse-surface validate`, `git diff --check`, and ADR-001
|
|
consistency checks.
|
|
|
|
## Out of Scope
|
|
|
|
- Host or operate the registered capabilities themselves.
|
|
- Replace package registries, service catalogs, issue trackers, or project
|
|
management systems.
|
|
- Judge internal code quality as capability maturity.
|
|
- Own unrelated adjacent systems or make irreversible operational decisions
|
|
without human approval.
|
|
|
|
## What Is Possible Now
|
|
|
|
The MVP registry foundation plus CLI tooling (REUSE-WP-0003) is in place. Humans
|
|
and agents can:
|
|
|
|
- **Discover capabilities** via `registry/indexes/capabilities.yaml` or
|
|
`reuse-surface query`
|
|
- **Add a new capability** at D0/A0/C0/R0 using
|
|
`templates/capability-entry.template.md`
|
|
- **Promote capabilities** with evidence, optional `promotion_history`, and index
|
|
vector updates
|
|
- **Compare candidates** using maturity vectors, scope, relations, and consumer
|
|
guidance
|
|
- **Record expectations** through `external_evidence.completeness` and
|
|
`external_evidence.reliability`
|
|
- **Validate entries automatically** with `reuse-surface validate`
|
|
- **Export a machine-readable bundle** with `reuse-surface export`
|
|
- **Detect overlap candidates** with `reuse-surface overlaps`
|
|
- **Generate a human-readable catalog** with `reuse-surface catalog`
|
|
- **Avoid duplicates** by querying the index and checking overlaps before adding entries
|
|
|
|
Registry tooling availability is **A3** (CLI). The registry product itself is
|
|
still documentation-first for authoring; consumption combines Markdown entries,
|
|
the index, and CLI automation.
|
|
|
|
## What Is Not Possible Yet
|
|
|
|
- Interactive catalog site with live search beyond static HTML export
|
|
- Capability graph visualization
|
|
- Federation across repositories or organizations
|
|
- Packaged releases beyond local `pip install -e .` and Gitea CI validation
|
|
|
|
See `tools/README.md` for command reference.
|
|
|
|
## Current State
|
|
|
|
- Status: active MVP registry with CLI tooling.
|
|
- Six helix_forge capabilities are registered in `registry/capabilities/`.
|
|
- `reuse-surface` CLI provides `validate`, `query`, and `export` via
|
|
`pyproject.toml` and `reuse_surface/`.
|
|
- `docs/CapabilityRegistryConcept.md` and `docs/IntentScopeGapAnalysis.md`
|
|
document onboarding and intent-scope tracking.
|
|
- CI validates the registry on push/PR via `.gitea/workflows/ci.yml`.
|
|
- Generated catalog: `docs/CapabilityCatalog.md` and `docs/catalog/index.html`.
|
|
- Finished workplans: `REUSE-WP-0001` through `REUSE-WP-0004`.
|
|
- **Self-assessed vector:** `D5 / A3 / C4 / R2` (see gap analysis).
|
|
|
|
## Repository Layout
|
|
|
|
```text
|
|
reuse-surface/
|
|
├── INTENT.md
|
|
├── SCOPE.md
|
|
├── AGENTS.md
|
|
├── pyproject.toml
|
|
├── reuse_surface/
|
|
├── specs/
|
|
├── schemas/
|
|
├── templates/
|
|
├── registry/
|
|
├── docs/
|
|
├── tools/
|
|
└── workplans/
|
|
```
|
|
|
|
## Getting Oriented
|
|
|
|
- Start with: INTENT.md
|
|
- Registry concept: docs/CapabilityRegistryConcept.md
|
|
- Intent vs scope gaps: docs/IntentScopeGapAnalysis.md
|
|
- Product requirements: specs/ProductRequirementsDocument.md
|
|
- Use cases: specs/UseCaseCatalog.md
|
|
- Maturity standard: specs/CapabilityMaturityStandard.md
|
|
- Registry index: registry/indexes/capabilities.yaml
|
|
- Registry guidance: registry/README.md
|
|
- Generated catalog: docs/CapabilityCatalog.md
|
|
- CLI reference: tools/README.md
|
|
- Agent instructions: AGENTS.md
|
|
- Workplans: workplans/ |