coulomb/reuse-surface
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
993ffb42ea9688d2c7909896b06bf81d391a8660
reuse-surface/SCOPE.md
tegwick 70a5003f6e
Some checks failed
ci / validate-registry (push) Has been cancelled
Details
Implement REUSE-WP-0013 registry establish, update, and stats 
Add stats, establish (scaffold, publish-check, discover), and update CLI
commands with optional llm-connect bridge, validate --root for sibling repos,
pytest coverage, and documentation for sibling registry onboarding.
2026-06-16 01:21:01 +02:00

7.2 KiB
Raw Blame History

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
  • 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
  • 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
  • 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-0012 finished/archived; REUSE-WP-0013 finished (registry establish/update/stats).
  • Assessment history: history/2026-06-15-intent-scope-assessment.md.
  • Self-assessed vector: D5 / A4 / C5 / R3 (see docs/IntentScopeGapAnalysis.md).

Repository Layout

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/
Reference in New Issue View Git Blame Copy Permalink