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

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
REUSE-WP-0005	workplan	Registry federation and relation graphs	helix_forge	reuse-surface	finished	codex	helix-forge	2026-06-15	2026-06-15	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

id: REUSE-WP-0005-T01
status: done
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

id: REUSE-WP-0005-T02
status: done
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

id: REUSE-WP-0005-T03
status: done
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

id: REUSE-WP-0005-T04
status: done
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

id: REUSE-WP-0005-T05
status: done
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.