generated from coulomb/repo-seed
tegwick
40ab8dded0
Some checks failed
ci / validate-registry (push) Has been cancelled
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.
116 lines
3.8 KiB
Markdown
116 lines
3.8 KiB
Markdown
---
|
|
id: REUSE-WP-0005
|
|
type: workplan
|
|
title: "Registry federation and relation graphs"
|
|
domain: helix_forge
|
|
repo: reuse-surface
|
|
status: finished
|
|
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: 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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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. |