Complete REUSE-WP-0005: registry federation and relation graphs

Add federation manifest and schema, federation compose and graph CLI commands,
relation cycle/reference checks, federated index and Mermaid graph artifacts,
RegistryFederation guide, and CI validation updates.

registry/README.md

@@ -31,7 +31,7 @@ registry/
    - `external_evidence.completeness.level: C0`
    - `external_evidence.reliability.level: R0`
 4. Add the entry to `registry/indexes/capabilities.yaml`.
-5. Run the manual validation checklist below.
+5. Run `reuse-surface validate --relations` and `reuse-surface federation compose`.
 
 Missing evidence is acceptable in the MVP when it is explicit rather than hidden.
 
@@ -129,6 +129,17 @@ Check for overlap in:
 When overlap is real, link entries with `relations.related_to`, `specializes`,
 or `generalizes` rather than creating silent duplicates.
 
+## Relation graph
+
+Regenerate the Mermaid graph after relation changes:
+
+```bash
+reuse-surface graph
+reuse-surface graph --check
+```
+
+Output: `docs/graph/capability-graph.mmd`
+
 ## Promote a capability
 
 1. Attach evidence appropriate to the target level in
@@ -137,5 +148,6 @@ or `generalizes` rather than creating silent duplicates.
 3. Append a `promotion_history` record with `date`, `dimension`, `from`, `to`,
    and `rationale` (optional `author`).
 4. Update `availability.current_artifacts` when a new consumption mode appears.
-5. Refresh the index `vector` and run `reuse-surface validate`.
+5. Refresh the index `vector` and run `reuse-surface validate --relations`.
+6. Run `reuse-surface federation compose` and `reuse-surface graph`.
 6. Set `status: reviewed` or `approved` when an assessor validates the entry.

registry/federation/sources.yaml

@@ -0,0 +1,35 @@
+# Federation manifest for helix_forge capability indexes.
+# Compose with: reuse-surface federation compose
+version: 1
+domain: helix_forge
+collision_policy: warn
+
+sources:
+  - repo: reuse-surface
+    index: registry/indexes/capabilities.yaml
+    enabled: true
+    required: true
+    domain: helix_forge
+    description: Primary local capability registry
+
+  # Enable when sibling repos publish registry/indexes/capabilities.yaml
+  - repo: state-hub
+    index: ~/state-hub/registry/indexes/capabilities.yaml
+    enabled: false
+    required: false
+    domain: helix_forge
+    description: State Hub coordination capabilities
+
+  - repo: feature-control
+    index: ~/feature-control/registry/indexes/capabilities.yaml
+    enabled: false
+    required: false
+    domain: helix_forge
+    description: Feature control domain capabilities
+
+  - repo: identity-canon
+    index: ~/identity-canon/registry/indexes/capabilities.yaml
+    enabled: false
+    required: false
+    domain: helix_forge
+    description: Identity canon research capabilities

registry/indexes/federated.yaml

@@ -0,0 +1,118 @@
+# Composed federated capability index. Regenerate with:
+# reuse-surface federation compose
+version: 1
+updated: '2026-06-15'
+domain: helix_forge
+collision_policy: warn
+sources:
+- repo: reuse-surface
+  index: registry/indexes/capabilities.yaml
+  count: 6
+capabilities:
+- id: capability.feature-control.evaluate
+  name: Feature Availability Evaluation
+  summary: Evaluate whether a feature is active, hidden, disabled, or unavailable
+    for a subject in context.
+  vector: D5 / A4 / C3 / R3
+  domain: helix_forge
+  status: draft
+  owner: feature-control
+  path: registry/capabilities/capability.feature-control.evaluate.md
+  tags:
+  - feature-control
+  - evaluation
+  - sdk
+  consumption_modes:
+  - SDK
+  - service API
+  source_repo: reuse-surface
+  source_index: registry/indexes/capabilities.yaml
+- id: capability.feature-control.rollout
+  name: Feature Rollout Control
+  summary: Gradually expose features to subjects across tenants, domains, groups,
+    or cohorts using rollout rules and staged availability.
+  vector: D4 / A2 / C2 / R1
+  domain: helix_forge
+  status: draft
+  owner: feature-control
+  path: registry/capabilities/capability.feature-control.rollout.md
+  tags:
+  - feature-control
+  - rollout
+  - planning
+  consumption_modes:
+  - source module
+  - SDK
+  source_repo: reuse-surface
+  source_index: registry/indexes/capabilities.yaml
+- id: capability.identity.subject-resolution
+  name: Identity Subject Resolution
+  summary: Resolve who or what is acting in a context by mapping principals, accounts,
+    actors, and identifiers to a stable subject model.
+  vector: D3 / A0 / C1 / R0
+  domain: helix_forge
+  status: draft
+  owner: identity-canon
+  path: registry/capabilities/capability.identity.subject-resolution.md
+  tags:
+  - identity
+  - subject
+  - architecture
+  consumption_modes:
+  - informational
+  source_repo: reuse-surface
+  source_index: registry/indexes/capabilities.yaml
+- id: capability.identity.vocabulary-canonicalize
+  name: Identity Vocabulary Canonicalization
+  summary: Define and maintain an implementation-neutral vocabulary for identity-related
+    concepts across overlapping domains.
+  vector: D4 / A0 / C2 / R0
+  domain: helix_forge
+  status: draft
+  owner: identity-canon
+  path: registry/capabilities/capability.identity.vocabulary-canonicalize.md
+  tags:
+  - identity
+  - terminology
+  - research
+  consumption_modes:
+  - informational
+  source_repo: reuse-surface
+  source_index: registry/indexes/capabilities.yaml
+- id: capability.registry.register
+  name: Capability Registration
+  summary: Register a new capability so it becomes visible for planning and implementation
+    reuse.
+  vector: D3 / A3 / C2 / R2
+  domain: helix_forge
+  status: draft
+  owner: reuse-surface
+  path: registry/capabilities/capability.registry.register.md
+  tags:
+  - registry
+  - governance
+  - meta
+  consumption_modes:
+  - informational
+  - markdown authoring
+  - cli
+  source_repo: reuse-surface
+  source_index: registry/indexes/capabilities.yaml
+- id: capability.statehub.workstream-coordinate
+  name: Workstream And Task Coordination
+  summary: Track active workstreams, tasks, progress, and consistency across domain
+    repositories through a local-first coordination service.
+  vector: D4 / A4 / C3 / R2
+  domain: helix_forge
+  status: draft
+  owner: state-hub
+  path: registry/capabilities/capability.statehub.workstream-coordinate.md
+  tags:
+  - state-hub
+  - coordination
+  - workplans
+  consumption_modes:
+  - service API
+  - HTTP REST
+  source_repo: reuse-surface
+  source_index: registry/indexes/capabilities.yaml