generated from coulomb/repo-seed
tegwick
14979f0602
Some checks failed
ci / validate-registry (push) Has been cancelled
Re-run federation sweep — hub-core now passes Gitea raw URL probe (12/60 blockers remain). Update workplan progress, SCOPE.md, IntentScopeGapAnalysis, and operator checklist to reflect T02/T03 closure and current compose stats (20 capabilities, 0 duplicate warnings).
175 lines
8.1 KiB
Markdown
175 lines
8.1 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`
|
|
- **Report registry gaps** with `reuse-surface report gaps` (roster blockers,
|
|
empty scaffolds, dedup stubs)
|
|
- **Bootstrap a sibling registry** with `reuse-surface establish --scaffold`
|
|
- **Verify index publish readiness** with `reuse-surface establish --publish-check`
|
|
- **View registry stats** with `reuse-surface stats` (per-repo or
|
|
`--roster registry/federation/local-repo-roster.yaml --federation-ready`)
|
|
- **Draft or refresh entries** with `reuse-surface establish --discover` and
|
|
`reuse-surface update` (optional llm-connect backend)
|
|
- **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
|
|
- **Fully fetchable federation** — hub registers **60** workstation repos; **12**
|
|
still fail Gitea raw URL probe (operator visibility). See
|
|
`registry/federation/local-repo-roster.yaml` and
|
|
`history/2026-06-16-wp0014-remaining-work-by-repo.md`
|
|
- **Multi-domain federation** — all indexed capabilities remain `helix_forge`
|
|
- **Planning analytics breadth** — `report gaps` shipped (REUSE-WP-0015-T03);
|
|
no roadmap views or standardization tracker beyond `overlaps` and compose
|
|
collision warnings
|
|
- **Managed platform posture** — hub runs as a container (A5 artifact) without
|
|
implemented SLO, multi-replica, or Postgres backing (criteria documented)
|
|
- **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, production hub, and
|
|
workstation-wide registry rollout (REUSE-WP-0014 finished).
|
|
- **Capabilities (reuse-surface):** 3 helix_forge entries in
|
|
`registry/capabilities/` (2 meta-registry + 1 `activity-core` stub until
|
|
publish passes).
|
|
- **Workstation roster:** 60 local git repos at `~/<slug>/` tracked in
|
|
`registry/federation/local-repo-roster.yaml` — all **established**, **60/60**
|
|
hub-registered, **48/60** publish-check pass.
|
|
- **Federation:** `registry/federation/sources.yaml` — **60** hub-synced URL
|
|
sources; `registry/indexes/federated.yaml` — **20** composed capability rows
|
|
(0 duplicate-ID warnings, 12 remote fetch warnings).
|
|
- **CLI / service:** `reuse_surface/` — validate, query, export, overlaps,
|
|
catalog, federation, graph, hub client, establish/update/stats, `serve`
|
|
(FastAPI hub).
|
|
- **Production hub:** `https://reuse.coulomb.social` — **60** repo registrations;
|
|
`GET /v1/federated` serves composed index from published raw URLs.
|
|
- **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`, `stats --roster`, `report gaps`.
|
|
- **Relation graph:** `docs/graph/capability-graph.mmd`, `docs/graph/index.html`.
|
|
- **Searchable catalog:** `docs/catalog/search.html`.
|
|
- **Workplans:** REUSE-WP-0001 through REUSE-WP-0014 finished (archived);
|
|
**REUSE-WP-0015** active (federation polish, dedup, planning analytics) —
|
|
T02/T03/T05 done; T01/T04 blocked on 12 Gitea publish failures.
|
|
- **Assessment history:** `history/` — intent/scope assessments, rollout
|
|
milestone, dedup plan, per-repo follow-up.
|
|
- **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, local-repo-roster.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/ |