open-reuse/registry/README.md

# open-reuse Registry

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

## Layout

```text
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](#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.

```text
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.

```text
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`.