diff --git a/SCOPE.md b/SCOPE.md index c2ad9db..2d57aba 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -102,8 +102,9 @@ See `tools/README.md` for command reference. - **Federated index:** `registry/indexes/federated.yaml` (local compose). - **Relation graph:** `docs/graph/capability-graph.mmd`, `docs/graph/index.html`. - **Searchable catalog:** `docs/catalog/search.html`. -- **Workplans:** REUSE-WP-0001 through REUSE-WP-0011 finished; WP-0011 archived - `workplans/archived/260615-REUSE-WP-0011-*.md`. +- **Workplans:** REUSE-WP-0001 through REUSE-WP-0011 finished; WP-0011 archived; + **REUSE-WP-0012** ready (federation scale + intent alignment). +- **Assessment history:** `history/2026-06-15-intent-scope-assessment.md`. - **Self-assessed vector:** `D5 / A4 / C4 / R3` (see `docs/IntentScopeGapAnalysis.md`). ## Repository Layout @@ -134,6 +135,7 @@ reuse-surface/ - Start with: INTENT.md - Registry concept: docs/CapabilityRegistryConcept.md - Intent vs scope gaps: docs/IntentScopeGapAnalysis.md +- Assessment snapshots: history/ - Product requirements: specs/ProductRequirementsDocument.md - Use cases: specs/UseCaseCatalog.md - Maturity standard: specs/CapabilityMaturityStandard.md diff --git a/docs/IntentScopeGapAnalysis.md b/docs/IntentScopeGapAnalysis.md index d821c28..75f7fab 100644 --- a/docs/IntentScopeGapAnalysis.md +++ b/docs/IntentScopeGapAnalysis.md @@ -224,6 +224,9 @@ archived workplans under `workplans/archived/`. | 22 | Hub hardening | Postgres option, backup, documented SLO (A5→A6 path) | Open | | 23 | External evidence program | Raise catalog R levels with consumer_feedback | Open | +**Workplan:** `REUSE-WP-0012` (ready). **Assessment snapshot:** +`history/2026-06-15-intent-scope-assessment.md`. + --- ## 9. Document Maintenance Rules @@ -247,4 +250,5 @@ archived workplans under `workplans/archived/`. | 2026-06-15 | REUSE-WP-0006 expanded registry to 12 capabilities | | 2026-06-15 | REUSE-WP-0007–0010 closed catalog UI, graph UI, pytest, network federation | | 2026-06-15 | REUSE-WP-0011 closed priority 17; hub live at reuse.coulomb.social | -| 2026-06-15 | Post-WP-0011 refresh: 20 capabilities, vector D5/A4/C4/R3, priorities 18–23 proposed | \ No newline at end of file +| 2026-06-15 | Post-WP-0011 refresh: 20 capabilities, vector D5/A4/C4/R3, priorities 18–23 proposed | +| 2026-06-15 | REUSE-WP-0012 proposed; assessment archived in `history/2026-06-15-intent-scope-assessment.md` | \ No newline at end of file diff --git a/history/2026-06-15-intent-scope-assessment.md b/history/2026-06-15-intent-scope-assessment.md new file mode 100644 index 0000000..373770f --- /dev/null +++ b/history/2026-06-15-intent-scope-assessment.md @@ -0,0 +1,135 @@ +# INTENT ↔ SCOPE State Assessment — reuse-surface + +**Date:** 2026-06-15 +**Author:** codex +**Trigger:** Post-REUSE-WP-0011 review; `SCOPE.md` and `docs/IntentScopeGapAnalysis.md` +refreshed (commit `5fcca42`). +**Follow-up workplan:** `workplans/REUSE-WP-0012-federation-scale-and-intent-alignment.md` + +--- + +## 1. Executive summary + +`reuse-surface` has completed its MVP-through-hub roadmap (REUSE-WP-0001 … +REUSE-WP-0011). The registry product delivers **20 helix_forge capabilities**, +**A3 CLI tooling**, a **production federation hub at A4** +(`https://reuse.coulomb.social`), federation compose, catalog/graph UIs, and +**20 pytest tests** with CI gates. + +INTENT and SCOPE are **aligned on the core model** (registry-first, four maturity +dimensions, human/agent consumers). Remaining work shifts from “build the +registry” to **scale federation membership**, **planning analytics**, and +**operational hardening**. + +**Self-assessed product vector:** `D5 / A4 / C4 / R3` + +--- + +## 2. Delivery snapshot + +| Area | State (2026-06-15) | +|---|---| +| Capability entries | 20 in `registry/capabilities/` | +| Index | `registry/indexes/capabilities.yaml` | +| CLI commands | validate, query, export, overlaps, catalog, federation, graph, hub, serve | +| Hosted hub | Railiance01 `92.205.62.239`; TLS live; image `cb7a6e4` | +| Hub registrations | 1 (`reuse-surface` → 12 capabilities on `/v1/federated`) | +| Federation (local) | `sources.yaml` + HTTP cache; `federated.yaml` composed in CI | +| Tests | 20 pytest; CI validate + federation + catalog + graph | +| Workplans | WP-0001 … WP-0011 finished; WP-0011 archived | +| Landing page | `railiance-apps` RAILIANCE-WP-0008 at `/` (browser only) | + +--- + +## 3. INTENT alignment + +### Aligned + +- Registry-first boundary (unregistered = invisible) +- Four maturity dimensions with internal/external evidence separation +- Human and agent consumption surfaces +- Technical foundation (“eventually technical”) — **met at MVP**: CLI + hub API +- Planning vs implementation reuse distinction in schema and workflows + +### Partial + +| INTENT expectation | Gap | +|---|---| +| Cross-repo / organizational reuse | All entries `helix_forge`; hub has one member | +| Eight success criteria fully met | Analytics, D7 tracking, “reuse as normal” still partial | +| Consumer reliability evidence | Catalog mostly R0–R2; no registry telemetry | + +### Drift (documentation) + +- `INTENT.md` “Initial Repository Role” tree predates `reuse_surface/hub/`, + `Dockerfile`, `workplans/archived/`, hub specs +- INTENT example entry uses `external_evidence.*.current`; schema uses `level` + +--- + +## 4. Success criteria scorecard + +| Criterion | Verdict | +|---|---| +| Find reusable capabilities before rebuilding | **Yes (MVP)** | +| Compare maturity consistently | **Yes** | +| Distinguish conceptual readiness from delivery | **Yes** | +| Distinguish internal vs external evidence | **Yes** | +| Plan prototype/MVP/enhancement/platform work | **Partial** | +| Identify gaps, duplicates, overlaps, standardization | **Partial** | +| Track progress to generalized capabilities | **Partial** | +| Make reuse normal in product/architecture work | **Partial** | + +--- + +## 5. Completeness and reliability + +**Completeness vs INTENT:** **C4 (Broadly Covered)** + +Core registry, tooling, and hub are in place. Federation membership and planning +analytics are the main bounded gaps. + +**Reliability vs INTENT:** **R3 (Usable)** + +CI, pytest, and production hub smoke checks support normal workflows. Not yet +**R4 Dependable** — no documented SLO, formal consumer feedback, or multi-replica +hub posture. + +--- + +## 6. Open gaps (priorities 18–23) + +| Priority | Gap | Suggested outcome | +|---|---|---| +| 18 | Sibling hub registrations | `state-hub` + one other repo on hub | +| 19 | `hub sync` | Write `sources.yaml` from hub state | +| 20 | Planning cohort reports | D5+/A4+ candidate export views | +| 21 | INTENT layout sync | Update INTENT.md tree and example shape | +| 22 | Hub hardening | Backup, Postgres option, documented SLO | +| 23 | External evidence program | Raise catalog R levels with feedback fields | + +Captured in `docs/IntentScopeGapAnalysis.md` section 8 and +**REUSE-WP-0012**. + +--- + +## 7. Recommendations + +1. **Execute REUSE-WP-0012** in federation-first order: hub membership and + `hub sync` before analytics and hardening. +2. **Coordinate sibling repos** — hub registration is blocked until domains + publish raw `capabilities.yaml` URLs (document publish contract in WP-0012). +3. **Refresh INTENT.md** early in WP-0012 to reduce contributor confusion. +4. **Defer A6 hub posture** until multi-replica or backup requirements are + explicit; current SQLite single-replica is acceptable for helix_forge scale. + +--- + +## 8. References + +- `INTENT.md` — product north star +- `SCOPE.md` — delivery truth (updated 2026-06-15) +- `docs/IntentScopeGapAnalysis.md` — living gap tracker +- `docs/RegistryFederation.md` — hub + local compose workflows +- `specs/FederationHubAPI.md` — hub API contract +- `workplans/archived/260615-REUSE-WP-0011-*.md` — hub delivery record \ No newline at end of file diff --git a/history/README.md b/history/README.md new file mode 100644 index 0000000..e47b730 --- /dev/null +++ b/history/README.md @@ -0,0 +1,9 @@ +# History + +Point-in-time assessments and milestone snapshots for `reuse-surface`. These +files are archival context — delivery truth remains in `SCOPE.md`; product truth +in `INTENT.md`; living delta tracking in `docs/IntentScopeGapAnalysis.md`. + +| Date | Artifact | Summary | +|---|---|---| +| 2026-06-15 | [2026-06-15-intent-scope-assessment.md](2026-06-15-intent-scope-assessment.md) | Post-WP-0011 INTENT↔SCOPE assessment; priorities 18–23 | \ No newline at end of file diff --git a/workplans/REUSE-WP-0012-federation-scale-and-intent-alignment.md b/workplans/REUSE-WP-0012-federation-scale-and-intent-alignment.md new file mode 100644 index 0000000..f120740 --- /dev/null +++ b/workplans/REUSE-WP-0012-federation-scale-and-intent-alignment.md @@ -0,0 +1,193 @@ +--- +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 \ No newline at end of file