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.

registry/README.md

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

registry/indexes/integrations.yaml

@@ -0,0 +1,19 @@
+version: 1
+updated: '2026-06-24'
+domain: infotech
+schema: schemas/integration.schema.yaml
+integrations:
+  - id: markitect-quarkdown
+    name: Markitect Quarkdown Render Adapter
+    status: active
+    owner: markitect-quarkdown
+    reuse_mode: adapter
+    risk_level: medium
+    path: integration/quarkdown.integration.yaml
+    repo: markitect-quarkdown
+    upstream:
+      name: Quarkdown
+      project_url: https://github.com/iamgio/quarkdown
+    notes: >
+      Reference integration for adapter reuse mode. Definition lives in the
+      consuming repository; this index row is the registry discovery surface.

schemas/integration.schema.yaml

@@ -0,0 +1,261 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://open-reuse.local/schemas/integration.schema.yaml
+title: Integration Definition
+description: >
+  JSON Schema for open-reuse Integration Definition files (YAML). Aligns with
+  INTENT.md, ProductRequirementsDocument.md section 14.1, and registry format v0.1.
+type: object
+additionalProperties: false
+required:
+  - schema_version
+  - id
+  - name
+  - upstream
+  - reuse
+  - boundary
+  - validation
+  - maintenance
+properties:
+  schema_version:
+    type: string
+    enum:
+      - open-reuse.integration.v0.1
+      - open-reuse.integration.v1
+    description: >
+      Schema version. v0.1 is the canonical registry format; v1 is accepted for
+      early adopters and will converge on v0.1 field names.
+  id:
+    type: string
+    pattern: '^[a-z][a-z0-9-]*$'
+    description: Stable integration identifier (kebab-case slug).
+  name:
+    type: string
+    minLength: 1
+    description: Human-readable integration name.
+  description:
+    type: string
+    description: Optional summary of the integration purpose and value.
+  status:
+    $ref: '#/$defs/lifecycleStatus'
+  owner:
+    type: string
+    description: Team, repository, or accountable party for the integration asset.
+  local:
+    type: object
+    additionalProperties: false
+    properties:
+      repo:
+        type: string
+        description: Repository hosting the integration implementation.
+      path:
+        type: string
+        description: Path to the integration definition file within the repo.
+      system:
+        type: string
+        description: Local consuming system or product name.
+  upstream:
+    type: object
+    additionalProperties: false
+    required:
+      - name
+    properties:
+      name:
+        type: string
+        minLength: 1
+      project_url:
+        type: string
+        format: uri
+      homepage:
+        type: string
+        format: uri
+      version_policy:
+        type: string
+        description: >
+          Accepted upstream version range or tracking policy (e.g. semver range,
+          major-line policy, or tag pattern).
+      current_version:
+        type: string
+        description: Pinned or last-validated upstream version reference.
+      monitor:
+        type: object
+        additionalProperties: false
+        properties:
+          releases:
+            type: boolean
+          tags:
+            type: boolean
+          security_advisories:
+            type: boolean
+          license_changes:
+            type: boolean
+  reuse:
+    type: object
+    additionalProperties: false
+    required:
+      - primary_reuse_mode
+    properties:
+      primary_reuse_mode:
+        $ref: '#/$defs/reuseMode'
+      secondary_reuse_modes:
+        type: array
+        items:
+          $ref: '#/$defs/reuseMode'
+      risk_level:
+        type: string
+        enum: [low, low-medium, medium, high, very-high]
+      rationale:
+        type: string
+        description: Why this reuse mode classification applies.
+  boundary:
+    type: object
+    description: >
+      Explicit seam between the local system and reused upstream functionality.
+      Domain-specific keys are allowed beyond the recommended fields.
+    minProperties: 1
+    properties:
+      type:
+        type: string
+        enum:
+          - interface
+          - port
+          - adapter
+          - wrapper-service
+          - api-facade
+          - plugin-boundary
+          - cli-boundary
+          - schema-boundary
+          - event-contract
+          - file-copy-boundary
+      local_adapter:
+        type: string
+      local_interface:
+        type: string
+      reused_surface:
+        type: string
+      entry_point:
+        type: string
+      contracts:
+        type: array
+        items:
+          type: string
+      fragility_points:
+        type: array
+        items:
+          type: string
+    additionalProperties: true
+  runtime:
+    type: object
+    additionalProperties: true
+    description: Optional runtime assumptions required for the integration.
+  permissions:
+    type: object
+    additionalProperties: true
+    description: Optional permission or capability model mapping.
+  validation:
+    type: object
+    additionalProperties: false
+    required:
+      - harness
+    properties:
+      harness:
+        type: string
+        minLength: 1
+        description: Command or reference to the validation harness entry point.
+      skip_without_runtime:
+        type: boolean
+      checks:
+        type: array
+        items:
+          type: string
+      policy:
+        type: string
+        enum:
+          - required-before-update
+          - advisory
+          - on-escalation-only
+  update_policy:
+    type: object
+    additionalProperties: false
+    properties:
+      default_action:
+        type: string
+        enum:
+          - ignore
+          - monitor-only
+          - open-issue
+          - open-update-proposal
+          - open-pull-request
+          - auto-merge-after-validation
+          - require-maintainer-review
+          - block-update
+          - escalate
+      auto_eligible:
+        type: boolean
+        description: Whether automation may attempt updates without review.
+  risks:
+    type: object
+    additionalProperties: false
+    properties:
+      sensitivity:
+        type: array
+        items:
+          type: string
+      escalation_triggers:
+        type: array
+        items:
+          type: string
+  maintenance:
+    type: object
+    additionalProperties: false
+    minProperties: 1
+    properties:
+      maintainers:
+        type: array
+        minItems: 1
+        items:
+          type: string
+        description: People, teams, or automation identities accountable for review.
+      escalation_conditions:
+        type: array
+        items:
+          type: string
+      last_validated:
+        type: string
+        format: date
+      notes:
+        type: string
+  audit:
+    type: object
+    additionalProperties: false
+    properties:
+      registered_at:
+        type: string
+        format: date
+      updated_at:
+        type: string
+        format: date
+      registered_by:
+        type: string
+$defs:
+  lifecycleStatus:
+    type: string
+    enum:
+      - draft
+      - registered
+      - active
+      - needs_review
+      - degraded
+      - paused
+      - deprecated
+      - retired
+  reuseMode:
+    type: string
+    enum:
+      - dependency
+      - dependency-reuse
+      - plugin
+      - adapter
+      - component-extraction
+      - patch-overlay
+      - fork-continuation
+      - cli-boundary

templates/integration-entry.template.yaml

@@ -0,0 +1,87 @@
+# Copy to <consuming-repo>/integration/<id>.integration.yaml
+# Register the entry in open-reuse registry/indexes/integrations.yaml after review.
+schema_version: open-reuse.integration.v0.1
+id: example-integration
+name: Example Integration
+description: >
+  One paragraph describing the proven integration, its value, and the local
+  system it connects to upstream open-source software.
+status: draft
+owner: team-or-repo-slug
+
+local:
+  repo: example-repo
+  path: integration/example.integration.yaml
+  system: Example Product
+
+upstream:
+  name: Upstream Project
+  project_url: https://github.com/org/upstream
+  homepage: https://upstream.example/
+  version_policy: ">=1.0.0 <2.0.0"
+  current_version: "1.4.2"
+  monitor:
+    releases: true
+    tags: true
+    security_advisories: true
+    license_changes: true
+
+reuse:
+  primary_reuse_mode: adapter
+  secondary_reuse_modes:
+    - dependency-reuse
+  risk_level: medium
+  rationale: >
+    Upstream behavior is wrapped behind a local adapter interface; upstream
+    API changes require validation but do not directly touch local systems.
+
+boundary:
+  type: adapter
+  local_adapter: example.adapter.ExampleAdapter
+  local_interface: example.contracts.UpstreamPort
+  reused_surface: upstream public API / CLI
+  entry_point: example.adapters
+  contracts:
+    - example.integration.v1
+  fragility_points:
+    - CLI flag changes
+    - output format changes
+
+runtime:
+  required:
+    - Upstream CLI 1.x
+    - Python 3.11+
+
+validation:
+  harness: python3 -m pytest tests/integration/
+  skip_without_runtime: true
+  checks:
+    - contract compatibility
+    - golden-path smoke test
+    - failure-mode diagnostics
+  policy: required-before-update
+
+update_policy:
+  default_action: require-maintainer-review
+  auto_eligible: false
+
+risks:
+  sensitivity:
+    - breaking API changes
+    - license changes
+    - security advisories
+  escalation_triggers:
+    - validation failure
+    - upstream major release
+
+maintenance:
+  maintainers:
+    - team-platform
+  escalation_conditions:
+    - upstream release detected
+    - validation failure
+    - dependency requirement change
+
+audit:
+  registered_at: "2026-06-24"
+  registered_by: integration-maintainer

workplans/OPEN-WP-0002-integration-asset-registry.md

@@ -4,11 +4,11 @@ type: workplan
 title: "Integration asset registry foundation"
 domain: infotech
 repo: open-reuse
-status: ready
+status: finished
 owner: codex
 topic_slug: infotech
 created: "2026-06-22"
-updated: "2026-06-22"
+updated: "2026-06-24"
 state_hub_workstream_id: "07cec732-6526-48e4-84d0-373e4abcb6d4"
 ---
 
@@ -20,9 +20,19 @@ Establish registry format for managed OSS integration assets.
 
 ```task
 id: OPEN-WP-0002-T01
-status: todo
+status: done
 priority: high
 state_hub_task_id: "b55b4413-2053-40bd-bee1-d138937f0b4f"
 ```
 
+Result 2026-06-24: Integration Definition schema v0.1, template, index, and
+lifecycle documentation.
+
 Define integration asset schema in `registry/` and document analyze→classify→refactor→maintain loop.
+
+Deliverables:
+
+- `schemas/integration.schema.yaml` — JSON Schema for Integration Definitions
+- `templates/integration-entry.template.yaml` — authoring template
+- `registry/indexes/integrations.yaml` — discovery index with markitect-quarkdown reference
+- `registry/README.md` — analyze→classify→refactor→maintain loop and validation checklist