135 lines
5 KiB
Markdown
135 lines
5 KiB
Markdown
|
# 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
|