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

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

Terminology note: Historical text in this archived workplan may use the legacy term "workstream". The fleet term is workplan (canon/standards/workplan-terminology-fleet_v0.1.md).

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

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

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

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

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:

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

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

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

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

• 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
• 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 documented (operator verify on Railiance01)
• 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.