From f218a5305ca93cdebf9a9b453501f11b9a2cb3bf Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 15 Jun 2026 01:34:36 +0200 Subject: [PATCH] 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 | 5 + .../REUSE-WP-0005-registry-federation.md | 116 ++++++++++++++++++ 2 files changed, 121 insertions(+) create mode 100644 workplans/REUSE-WP-0005-registry-federation.md diff --git a/workplans/REUSE-WP-0004-registry-hardening.md b/workplans/REUSE-WP-0004-registry-hardening.md index da60f56..c004a5d 100644 --- a/workplans/REUSE-WP-0004-registry-hardening.md +++ b/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 diff --git a/workplans/REUSE-WP-0005-registry-federation.md b/workplans/REUSE-WP-0005-registry-federation.md new file mode 100644 index 0000000..b81789d --- /dev/null +++ b/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. \ No newline at end of file