reuse-surface/workplans/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: ready
owner: codex
topic_slug: helix-forge
created: "2026-06-15"
updated: "2026-06-15"
---

# 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: todo
priority: high
```

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: todo
priority: high
```

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: todo
priority: medium
```

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: todo
priority: medium
```

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: todo
priority: medium
```

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: todo
priority: low
```

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

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