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).
155 lines
6.8 KiB
Markdown
155 lines
6.8 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, hub service, 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 (except the federation
|
|
hub coordinator, which stores repo metadata and index URLs only).
|
|
- 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, CLI tooling (REUSE-WP-0003), federation stack
|
|
(WP-0005/0010), and hosted hub (WP-0011) are in place. Humans and agents can:
|
|
|
|
- **Discover capabilities** via `registry/indexes/capabilities.yaml`,
|
|
`reuse-surface query`, or `GET https://reuse.coulomb.social/v1/federated`
|
|
- **Add a new capability** at D0/A0/C0/R0 using
|
|
`templates/capability-entry.template.md`
|
|
- **Promote capabilities** with evidence, `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`
|
|
- **Browse a searchable catalog** at `docs/catalog/search.html`
|
|
- **Compose federated indexes** with `reuse-surface federation compose`
|
|
(local paths and remote HTTP URLs with cache)
|
|
- **Register federation sources on the hosted hub** with `reuse-surface hub`
|
|
against `https://reuse.coulomb.social`
|
|
- **Sync local federation manifest from hub** with `reuse-surface hub sync`
|
|
- **Export planning cohorts** with `reuse-surface report cohorts`
|
|
- **Run the hub locally or in a container** with `reuse-surface serve`
|
|
- **Generate relation graphs** with `reuse-surface graph`
|
|
- **Explore relations interactively** at `docs/graph/index.html`
|
|
- **Avoid duplicates** by querying the index and checking overlaps before adding
|
|
entries
|
|
|
|
Registry **tooling** availability is **A4** (CLI plus hosted hub HTTP API).
|
|
Registry **authoring** remains Markdown-first; consumption combines entries, the
|
|
index, CLI automation, and the production hub.
|
|
|
|
## What Is Not Possible Yet
|
|
|
|
- **Automatic hub refresh** — federated compose is on-demand; no polling or
|
|
webhooks
|
|
- **Cross-repo federation at scale** — hub has one registered repo; sibling
|
|
domains must publish capability indexes before registration (see
|
|
`history/2026-06-16-hub-registration-blocks.md`)
|
|
- **Planning analytics beyond cohorts** — no gap reports, roadmap views, or
|
|
standardization tracker beyond `report cohorts`, query, and export
|
|
- **Managed platform posture** — hub runs as a container (A5 artifact) without
|
|
documented SLO, multi-replica, or Postgres backing
|
|
- **Formal consumer feedback loop** for registry workflows (reliability evidence
|
|
is mostly structural: CI/tests, not production telemetry)
|
|
|
|
See `tools/README.md` for command reference.
|
|
|
|
## Current State
|
|
|
|
- **Status:** active MVP registry with CLI, federation, and production hub.
|
|
- **Capabilities:** 20 helix_forge entries in `registry/capabilities/`.
|
|
- **CLI / service:** `reuse_surface/` — validate, query, export, overlaps,
|
|
catalog, federation, graph, hub client, `serve` (FastAPI hub).
|
|
- **Production hub:** `https://reuse.coulomb.social` on Railiance01
|
|
(`92.205.62.239`); image `gitea.coulomb.social/coulomb/reuse-surface:cb7a6e4`;
|
|
TLS live; dogfood registration for `reuse-surface` (12 capabilities composed
|
|
on `/v1/federated`).
|
|
- **Specs:** `specs/FederationHubAPI.md`, `schemas/hub-registration.schema.yaml`.
|
|
- **Docs:** `docs/CapabilityRegistryConcept.md`, `docs/RegistryFederation.md`,
|
|
`docs/IntentScopeGapAnalysis.md`, deploy guide `docs/deploy/reuse-kubernetes.md`.
|
|
- **CI:** `.gitea/workflows/ci.yml` — validate, federation compose, catalog,
|
|
graph, pytest, informational `report cohorts`.
|
|
- **Federated index:** `registry/indexes/federated.yaml` (local compose).
|
|
- **Relation graph:** `docs/graph/capability-graph.mmd`, `docs/graph/index.html`.
|
|
- **Searchable catalog:** `docs/catalog/search.html`.
|
|
- **Workplans:** REUSE-WP-0001 through REUSE-WP-0011 finished; WP-0011 archived;
|
|
**REUSE-WP-0012** finished (federation scale + intent alignment).
|
|
- **Assessment history:** `history/2026-06-15-intent-scope-assessment.md`.
|
|
- **Self-assessed vector:** `D5 / A4 / C5 / R3` (see `docs/IntentScopeGapAnalysis.md`).
|
|
|
|
## Repository Layout
|
|
|
|
```text
|
|
reuse-surface/
|
|
├── INTENT.md
|
|
├── SCOPE.md
|
|
├── AGENTS.md
|
|
├── pyproject.toml
|
|
├── Dockerfile
|
|
├── reuse_surface/ # CLI, hub service, federation, graph, catalog
|
|
├── specs/
|
|
├── schemas/
|
|
├── templates/
|
|
├── registry/
|
|
│ ├── capabilities/ # per-entry Markdown
|
|
│ ├── indexes/ # capabilities.yaml, federated.yaml
|
|
│ └── federation/ # sources.yaml, cache/
|
|
├── docs/
|
|
├── tools/
|
|
└── workplans/
|
|
└── archived/
|
|
```
|
|
|
|
## Getting Oriented
|
|
|
|
- Start with: INTENT.md
|
|
- Registry concept: docs/CapabilityRegistryConcept.md
|
|
- Intent vs scope gaps: docs/IntentScopeGapAnalysis.md
|
|
- Assessment snapshots: history/
|
|
- Product requirements: specs/ProductRequirementsDocument.md
|
|
- Use cases: specs/UseCaseCatalog.md
|
|
- Maturity standard: specs/CapabilityMaturityStandard.md
|
|
- Hub API: specs/FederationHubAPI.md
|
|
- Registry index: registry/indexes/capabilities.yaml
|
|
- Registry guidance: registry/README.md
|
|
- Federation guide: docs/RegistryFederation.md
|
|
- Hub deployment: docs/deploy/reuse-kubernetes.md
|
|
- Generated catalog: docs/CapabilityCatalog.md
|
|
- Searchable catalog: docs/catalog/search.html
|
|
- Relation graph: docs/graph/capability-graph.mmd
|
|
- Graph explorer: docs/graph/index.html
|
|
- CLI reference: tools/README.md
|
|
- Agent instructions: AGENTS.md
|
|
- Workplans: workplans/ |