reuse-surface/workplans/archived/260616-REUSE-WP-0012-federation-scale-and-intent-alignment.md

---
id: REUSE-WP-0012
type: workplan
title: "Federation scale, planning analytics, and intent alignment"
domain: helix_forge
repo: reuse-surface
status: finished
owner: codex
topic_slug: helix-forge
created: "2026-06-15"
updated: "2026-06-16"
state_hub_workstream_id: "fb0b6067-6b73-410c-a73c-8bb81a55136a"
---

# Federation scale, planning analytics, and intent alignment

Follow-up to `history/2026-06-15-intent-scope-assessment.md` and
`docs/IntentScopeGapAnalysis.md` priorities **18–23**. REUSE-WP-0011 delivered
the hosted hub; this workplan closes the next INTENT↔SCOPE gaps: **cross-repo
membership**, **offline hub sync**, **planning cohort exports**, **INTENT doc
alignment**, **hub operational hardening**, and **external evidence depth**.

**Baseline vector:** `D5 / A4 / C4 / R3`  
**Target vector after completion:** `D5 / A4 / C5 / R3` (raise completeness via
federation breadth and planning reports; reliability unchanged until feedback
program lands)

## Assessment reference

| Priority | Gap | This workplan |
|---|---|---|
| 18 | Sibling hub registrations | T01 |
| 19 | `hub sync` | T02 |
| 20 | Planning cohort reports | T03 |
| 21 | INTENT layout sync | T04 |
| 22 | Hub hardening | T05 |
| 23 | External evidence program | T06 |

## Suggested execution order

```text
T04 (INTENT alignment — unblocks contributors)
  → T01 (hub membership — may wait on sibling index URLs)
  → T02 (hub sync — after T01 proves multi-repo hub state)
  → T03 (cohort reports — independent after query/export stable)
  → T06 (evidence program — can parallel T03)
  → T05 (hub hardening — document/design; implement only if requirements clear)
```

## Dependencies

| Dependency | Owner | Notes |
|---|---|---|
| Published sibling `capabilities.yaml` URLs | Domain repos | T01 blocked per repo without raw index |
| Production hub | RAILIANCE-WP-0007 | Live at `reuse.coulomb.social` |
| Hub token | Operator | `reuse-surface-env` secret on Railiance01 |

---

## Register Sibling Repos On Hub

```task
id: REUSE-WP-0012-T01
status: done
priority: high
state_hub_task_id: "db56e4d8-6bc8-435a-a202-324a20e6928c"
```

Close gap priority **18**. Register at least **two** additional helix_forge repos
on the production hub (target: `state-hub` plus one other with a published
index URL).

Deliverables:

- Document index publish contract in `docs/RegistryFederation.md` (raw Gitea URL
  shape, required fields, auth expectations)
- Register repos via `reuse-surface hub register` against production hub
- Verify `GET /v1/federated` shows merged capabilities with `source_repo`
  attribution
- Record registration evidence in workplan or `history/` note

**Blocked on:** sibling repos publishing `registry/indexes/capabilities.yaml` at
stable raw URLs.

## Implement hub sync

```task
id: REUSE-WP-0012-T02
status: done
priority: high
state_hub_task_id: "521d9c57-80f0-4409-8c20-ad7b9d227128"
```

Close gap priority **19**. Add `reuse-surface hub sync` that writes
`registry/federation/sources.yaml` from hub `GET /v1/repos` state.

Requirements:

- Preserve local-only sources optionally (`--merge` vs `--replace`)
- Map hub fields to federation schema `url` sources
- Document in `tools/README.md` and `docs/RegistryFederation.md`
- Pytest coverage with mocked hub HTTP
- `federation compose` still works offline after sync

## Add Planning Cohort Reports

```task
id: REUSE-WP-0012-T03
status: done
priority: medium
state_hub_task_id: "f3519f29-cfa6-4732-83e7-8833d56c0263"
```

Close gap priority **20**. Extend CLI with cohort export for planning and
implementation reuse decisions.

Suggested surface:

```bash
reuse-surface report cohorts
reuse-surface report cohorts --planning-min D5 --availability-max A1
reuse-surface report cohorts --implementation-min A4
```

Output: Markdown or JSON listing capability IDs, vectors, and consumption modes
matching filters. Wire into CI as a non-failing informational step or document
as manual planning command only.

Update `docs/IntentScopeGapAnalysis.md` success criteria notes when shipped.

## Align INTENT With Delivered Layout

```task
id: REUSE-WP-0012-T04
status: done
priority: medium
state_hub_task_id: "cdd0bb1e-2ac8-46ef-b5ef-c9d410c6a3ad"
```

Close gap priority **21**. Update `INTENT.md` only (product truth unchanged):

- Replace “Initial Repository Role” tree with current layout from `SCOPE.md`
  (include `reuse_surface/`, hub, `history/`, `workplans/archived/`)
- Fix registry entry example to use `external_evidence.*.level`
- Add pointers to `docs/RegistryFederation.md`, `specs/FederationHubAPI.md`,
  `history/2026-06-15-intent-scope-assessment.md`

## Document Hub Hardening Path

```task
id: REUSE-WP-0012-T05
status: done
priority: medium
state_hub_task_id: "35490a85-34b5-4dcc-9039-156a77320672"
```

Close gap priority **22**. Produce operator-facing hardening guidance without
mandating immediate implementation.

Deliverables:

- `docs/deploy/reuse-kubernetes.md` section: backup (SQLite PVC), cert renewal,
  token rotation, image promotion checklist
- Decision note: SQLite vs Postgres cnpg — criteria for switching (multi-replica,
  RPO/RTO). Implementation deferred unless operator requests
- Optional: spike issue only if Postgres migration is approved

Target availability narrative: clarify A5 container deployed, A6 path documented.

## External Evidence Program

```task
id: REUSE-WP-0012-T06
status: done
priority: low
state_hub_task_id: "5509cec2-2d2e-4592-b9a5-09902a652705"
```

Close gap priority **23**. Raise external evidence quality across the catalog.

Scope:

- Define minimum evidence checklist in `registry/README.md` for promoting R1→R3
- Update **at least three** capability entries with `consumer_feedback`,
  `known_reliability_risks`, or resolved risks where evidence exists
- Self-assess `capability.registry.register` reliability toward R3 with hub
  production smoke + CI as cited evidence
- Refresh `docs/IntentScopeGapAnalysis.md` reliability section

---

## Acceptance

- [x] Hub federates **≥3 repos** (including reuse-surface) OR T01 documents
      explicit blocks per sibling with owner follow-ups — **blocks documented**
      in `history/2026-06-16-hub-registration-blocks.md`
- [x] `hub sync` materializes valid `sources.yaml` from hub state
- [x] `report cohorts` (or equivalent) exports planning/implementation filters
- [x] `INTENT.md` layout matches delivered repository structure
- [x] Hub hardening doc complete; backup/restore steps documented (operator verify on Railiance01)
- [x] Gap analysis priorities 18–23 marked closed or explicitly deferred with rationale

## Completion notes (2026-06-16)

- **T01:** Publish contract in `docs/RegistryFederation.md`; sibling 303 probes in
  `history/2026-06-16-hub-registration-blocks.md`. Hub remains at 1 repo until
  siblings publish indexes.
- **T02:** `reuse_surface/hub_sync.py`, `reuse-surface hub sync`, pytest in
  `tests/test_hub_sync.py`.
- **T03:** `reuse_surface/reports.py`, `reuse-surface report cohorts`, pytest in
  `tests/test_reports.py`.
- **T04:** `INTENT.md` layout aligned with `SCOPE.md`.
- **T05:** Hardening section in `docs/deploy/reuse-kubernetes.md`.
- **T06:** R1→R3 checklist in `registry/README.md`; entries `capability.registry.register`,
  `capability.registry.validate`, `capability.statehub.progress-log` updated.