coulomb/reuse-surface
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
270065ff58e1cc4d7bc36d82f990598f79f5915b
reuse-surface/SCOPE.md
tegwick 270065ff58
Some checks failed
ci / validate-registry (push) Has been cancelled
Details
Implement REUSE-WP-0012 federation scale and intent alignment 
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).
2026-06-16 00:42:50 +02:00

6.8 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
  • 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

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