open-reuse/registry/README.md

open-reuse Registry

Markdown-first registry for managed open-source integration assets.

Layout

registry/
├── README.md
├── integrations/          # optional local definitions (most live in consuming repos)
├── capabilities/          # federation capability index (reuse-surface)
└── indexes/
    ├── integrations.yaml  # integration discovery index
    └── capabilities.yaml  # capability federation index
schemas/
└── integration.schema.yaml
templates/
└── integration-entry.template.yaml

• Integration definitions are YAML files conforming to schemas/integration.schema.yaml. They usually live in the consuming repository (e.g. integration/<id>.integration.yaml).
• Index at indexes/integrations.yaml is the discovery surface for registered integrations across the portfolio.
• Template at templates/integration-entry.template.yaml is the authoring starting point for new definitions.
• Capability index at indexes/capabilities.yaml supports reuse-surface federation; see Capability Registry below.

Integration lifecycle loop

open-reuse starts after an integration has proven value. The registry captures the outcome of a structured loop that turns informal reuse into a managed asset.

Analyze → Classify → Refactor → Maintain

1. Analyze

Understand the working integration before encoding it.

Question	Artifact
What upstream project is reused?	upstream.name, upstream.project_url
What local system depends on it?	local.system, owner
What surfaces are actually reused?	boundary.reused_surface, boundary.contracts
What runtime assumptions exist?	runtime
What breaks when upstream changes?	risks.sensitivity, boundary.fragility_points
How is correctness proven today?	validation.harness, validation.checks

Output: enough context to classify reuse mode and draw a defensible boundary. Incomplete analysis is acceptable in status: draft; missing upstream or boundary information blocks promotion to registered.

2. Classify

Assign an explicit reuse mode so risk, validation depth, and update policy can be chosen systematically.

Reuse mode	Typical risk	Notes
dependency / dependency-reuse	Low	Package, library, image, or service consumption
plugin	Low–medium	Official extension points
adapter	Medium	Upstream wrapped behind a local interface
component-extraction	High	Selected internal parts reused
patch-overlay	High	Local patches on upstream
fork-continuation	Very high	Divergent fork, upstream-aware
cli-boundary	Medium	CLI invocation as the integration seam

Record classification in reuse.primary_reuse_mode, optional reuse.secondary_reuse_modes, and reuse.risk_level.

Output: reuse block with rationale. Unclassified integrations remain incomplete until primary_reuse_mode is set.

3. Refactor

Establish a clear, testable boundary between local systems and upstream change.

The boundary block documents the seam:

• Type — adapter, cli-boundary, plugin-boundary, schema-boundary, etc.
• Local side — local_adapter, local_interface, entry_point
• Upstream side — reused_surface, contracts
• Fragility — fragility_points where upstream drift hurts first

Refactoring work happens in the consuming repository. The Integration Definition records the resulting boundary so automation and maintainers know what to protect.

Output: boundary with at least one concrete local/upstream reference. Domain-specific keys (e.g. markitect_adapter_id) are allowed.

4. Maintain

Register the definition, assign maintainers, and connect validation to ongoing upstream monitoring.

Concern	Field
Registry visibility	row in indexes/integrations.yaml
Accountability	maintenance.maintainers
When humans must act	maintenance.escalation_conditions, risks.escalation_triggers
Proving continuity	validation.harness
Update behavior	update_policy.default_action
Lifecycle	status (see schema enum)

Output: integration moves from draft → registered → active once maintainers, validation, and index registration are in place.

Full product lifecycle (context)

The four-step loop above is the minimum path to a registry entry. The broader open-reuse lifecycle (see INTENT.md) also includes reframe, register, monitor, auto-update, validate, and escalate. Registry format v0.1 encodes the knowledge those later stages require.

Prove Value
→ Analyze → Classify → Refactor → Create Integration Definition
→ Register in indexes/integrations.yaml
→ Monitor upstream → Validate → Update or Escalate

Add a new integration (v0.1)

1. Copy templates/integration-entry.template.yaml to the consuming repo at integration/<id>.integration.yaml.
2. Complete the Analyze and Classify sections: upstream, reuse mode, risks.
3. Complete the Refactor section: boundary with explicit local/upstream seams.
4. Complete the Maintain section: validation harness, maintainers, update policy.
5. Set schema_version: open-reuse.integration.v0.1.
6. Add a row to registry/indexes/integrations.yaml with id, path, repo, reuse_mode, and upstream summary.
7. Validate manually (checklist below) before setting status: active.

Early adopters may use schema_version: open-reuse.integration.v1; the schema accepts both. New entries should use v0.1.

Manual validation checklist

Use until an automated CLI validator ships.

Required fields

• schema_version is open-reuse.integration.v0.1 (or accepted v1 draft)
• id matches ^[a-z][a-z0-9-]*$
• name, upstream.name, reuse.primary_reuse_mode are present
• boundary has at least one local and one upstream reference
• validation.harness is a runnable command or documented CI entry point
• maintenance includes maintainers or escalation_conditions

Promotion gates

Target status	Requires
draft	Core identity + upstream + reuse mode
registered	Boundary + validation harness + index row
active	Maintainers + update policy + passing validation

Enum checks

Reuse modes: see schema reuseMode enum in schemas/integration.schema.yaml.
Lifecycle status: draft, registered, active, needs_review, degraded, paused, deprecated, retired.
Update actions: ignore, monitor-only, open-issue, open-update-proposal, open-pull-request, auto-merge-after-validation, require-maintainer-review, block-update, escalate.

Index checks

• New entry appears in indexes/integrations.yaml
• path and repo point to the definition file in the consuming repository
• reuse_mode matches reuse.primary_reuse_mode in the definition
• upstream.name matches the definition

Reference integration

markitect-quarkdown provides the first real-world adapter integration:

• Definition: markitect-quarkdown/integration/quarkdown.integration.yaml
• Index row: indexes/integrations.yaml → markitect-quarkdown

Use it as a worked example for adapter + cli-boundary reuse.

Capability registry

The capability index supports reuse-surface federation for cross-repo planning.

1. Copy a capability entry template (see reuse-surface templates/capability-entry.template.md).
2. Add the row to indexes/capabilities.yaml.
3. Run reuse-surface validate from a checkout with the CLI installed.
4. Merge to main and verify publish with reuse-surface establish --publish-check.

Federation contract: reuse-surface docs/RegistryFederation.md.