Add REUSE-WP-0005 workplan for registry federation and relation graphs

Seed follow-up work to compose federated capability indexes from configured
helix_forge sources and generate Mermaid relation graphs per gap analysis
priorities 12 and 14.

workplans/REUSE-WP-0004-registry-hardening.md

@@ -9,6 +9,7 @@ owner: codex
 topic_slug: helix-forge
 created: "2026-06-15"
 updated: "2026-06-15"
+state_hub_workstream_id: "8e792e1e-8f28-4f7f-8c53-2b04ef078e61"
 ---
 
 # Registry hardening: CI, overlap detection, and catalog
@@ -23,6 +24,7 @@ reporting (UC-RS-015), and a generated human-readable catalog (UC-RS-018).
 id: REUSE-WP-0004-T01
 status: done
 priority: high
+state_hub_task_id: "750e7fd6-f9b3-4945-a2f5-9a405ca3af6b"
 ```
 
 Add `.gitea/workflows/ci.yml` that runs on push and pull requests to `main`.
@@ -35,6 +37,7 @@ Install the package and run `reuse-surface validate`. Document the workflow in
 id: REUSE-WP-0004-T02
 status: done
 priority: high
+state_hub_task_id: "8c5febb0-758d-4983-958c-093e5c481f2c"
 ```
 
 Add `reuse-surface overlaps` that flags potential duplicate or overlapping
@@ -47,6 +50,7 @@ Document usage in `registry/README.md` and `tools/README.md`.
 id: REUSE-WP-0004-T03
 status: done
 priority: medium
+state_hub_task_id: "2cae7d58-b943-4ef6-b404-2ad126450e0a"
 ```
 
 Add `reuse-surface catalog` that generates `docs/CapabilityCatalog.md` and
@@ -59,6 +63,7 @@ and show maturity vectors.
 id: REUSE-WP-0004-T04
 status: done
 priority: medium
+state_hub_task_id: "a9660e01-81af-45fb-8d51-4f16fbaa94c2"
 ```
 
 Update `SCOPE.md`, `tools/README.md`, and `docs/IntentScopeGapAnalysis.md` to

workplans/REUSE-WP-0005-registry-federation.md

@@ -0,0 +1,116 @@
+---
+id: REUSE-WP-0005
+type: workplan
+title: "Registry federation and relation graphs"
+domain: helix_forge
+repo: reuse-surface
+status: ready
+owner: codex
+topic_slug: helix-forge
+created: "2026-06-15"
+updated: "2026-06-15"
+state_hub_workstream_id: "df6a3b58-2c32-4893-8771-87a822c12aa5"
+---
+
+# Registry federation and relation graphs
+
+Follow-up to `docs/IntentScopeGapAnalysis.md` open priorities 12 and 14.
+Extend the registry beyond a single-repo index by composing federated indexes
+from configured sources and generating relation graphs for architects (UC-RS-016).
+
+## Design decisions
+
+- **Federation scope (MVP):** Filesystem-local index composition only. A manifest
+  lists index files from this repo and sibling helix_forge checkouts; no network
+  fetch or runtime federation service.
+- **Source attribution:** Federated entries carry `source_repo` and
+  `source_index` so ID collisions are visible, not silently merged.
+- **Graph output:** Mermaid diagram derived from entry `relations` fields;
+  suitable for docs and PR review, not interactive visualization yet.
+- **Cycle policy:** `depends_on` cycles are reported as warnings during graph
+  generation and federation compose validation.
+
+## Define Federation Manifest And Schema
+
+```task
+id: REUSE-WP-0005-T01
+status: todo
+priority: high
+state_hub_task_id: "9a9732ea-c546-49fe-bf61-0f3bdf94406a"
+```
+
+Create `schemas/federation.schema.yaml` and
+`registry/federation/sources.yaml` describing federation sources for
+helix_forge. The manifest must support:
+
+- Local primary index (`registry/indexes/capabilities.yaml`)
+- Optional sibling repo indexes via absolute or home-relative paths
+- Per-source `enabled`, `domain`, and `repo` metadata
+- Documented collision policy (`warn`, not auto-merge)
+
+Include commented placeholders for `state-hub`, `feature-control`, and
+`identity-canon` indexes to federate when those repos publish them.
+
+## Add Federation Compose Command
+
+```task
+id: REUSE-WP-0005-T02
+status: todo
+priority: high
+state_hub_task_id: "9539c609-ac44-40a7-90bc-6f294fe085b9"
+```
+
+Add `reuse-surface federation compose` that reads `registry/federation/sources.yaml`
+and writes `registry/indexes/federated.yaml`. Requirements:
+
+- Merge capability rows from all enabled sources
+- Preserve `source_repo`, `source_index`, and original `path` per entry
+- Warn on duplicate IDs across sources
+- Skip missing optional external indexes with a clear warning (not a hard fail)
+- Document command in `tools/README.md` and `AGENTS.md`
+
+## Add Relation Graph Command
+
+```task
+id: REUSE-WP-0005-T03
+status: todo
+priority: medium
+state_hub_task_id: "4f7e85a5-c73a-49b6-a044-ba1fabc54d8a"
+```
+
+Add `reuse-surface graph` that emits a Mermaid `graph LR` diagram from capability
+entry relations. Requirements:
+
+- Include all relation types present in entries
+- Write `docs/graph/capability-graph.mmd` by default; support `--stdout`
+- Nodes labeled with capability ID and compact vector from the index
+- Document regeneration in `registry/README.md`
+
+## Add Cycle And Broken-Reference Checks
+
+```task
+id: REUSE-WP-0005-T04
+status: todo
+priority: medium
+state_hub_task_id: "6f7e2913-9634-4ebb-841f-9024b35961ef"
+```
+
+Extend validation or graph generation to report:
+
+- `depends_on` cycles within the registered graph
+- Relation targets that reference unknown capability IDs in the composed index
+- Output as warnings via `reuse-surface graph --check` or `validate --relations`
+
+## Document Federation And Refresh Gap Analysis
+
+```task
+id: REUSE-WP-0005-T05
+status: todo
+priority: medium
+state_hub_task_id: "8d69121b-9961-41c2-8802-d9c5b5d94c69"
+```
+
+Create `docs/RegistryFederation.md` covering manifest format, compose workflow,
+collision handling, and how agents should query federated indexes. Update
+`SCOPE.md`, `docs/IntentScopeGapAnalysis.md`, and CI if federation compose
+should run in the validate pipeline.