generated from coulomb/repo-seed
Implement REUSE-WP-0012 federation scale and intent alignment
Some checks failed
ci / validate-registry (push) Has been cancelled
Some checks failed
ci / validate-registry (push) Has been cancelled
Add hub sync and report cohorts CLI commands with pytest coverage, document sibling index publish contract and hub hardening path, align INTENT layout, raise external evidence on three registry entries, and close gap priorities 19-23 (priority 18 deferred on sibling index blocks).
This commit is contained in:
@@ -0,0 +1,215 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user