generated from coulomb/repo-seed
feat(registry): add Integration Definition schema v0.1
Define the open-reuse integration asset registry format with JSON Schema, authoring template, discovery index, and analyze→classify→refactor→maintain lifecycle documentation. Validates against the markitect-quarkdown reference integration. Closes OPEN-WP-0002.
This commit is contained in:
@@ -1,12 +1,195 @@
|
||||
# Capability Registry
|
||||
# open-reuse Registry
|
||||
|
||||
Markdown-first capability index for federation and reuse planning.
|
||||
Markdown-first registry for managed open-source integration assets.
|
||||
|
||||
## Authoring
|
||||
## 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`.
|
||||
Federation contract: reuse-surface `docs/RegistryFederation.md`.
|
||||
Reference in New Issue
Block a user