generated from coulomb/repo-seed
tegwick
6473fa78d7
Refresh SCOPE.md for v0 operational state after WP-0002/0003/0008. Add history/ INTENT↔SCOPE assessment and ready workplan for the-custodian e2e shim to close the e2e-framework migration arc.
198 lines
8.8 KiB
Markdown
198 lines
8.8 KiB
Markdown
# INTENT ↔ SCOPE Gap Analysis — Post SAND-WP-0003
|
||
|
||
**Date:** 2026-06-23
|
||
**Author:** codex
|
||
**Trigger:** SAND-WP-0003 finished (wise-validator extraction); SAND-WP-0001/0002/0008
|
||
already complete. SCOPE.md stale (still described bootstrap / not-started state).
|
||
**Prior assessment:** none (first `history/` entry for sand-boxer)
|
||
|
||
---
|
||
|
||
## 1. Executive summary
|
||
|
||
sand-boxer has crossed from **bootstrap** to **v0 operational** for the self-hosted
|
||
compose path. The establishment half of `the-custodian/e2e-framework/` is migrated
|
||
(`ext.compose-ssh`); the validation half lives in **wise-validator** (`validate run`).
|
||
Host telemetry and canary self-deploy (SAND-WP-0008) make the repo self-sustained per
|
||
INTENT.
|
||
|
||
Remaining distance to INTENT is **migration completion** (the-custodian shim),
|
||
**extension breadth** (vm-packer, SaaS), **lifecycle depth** (TTL enforcement,
|
||
snapshots), and **operational maturity** (sandboxer01, reuse-surface publish,
|
||
security runbooks).
|
||
|
||
**Vector movement:** `D4/A1/C1/R1` (bootstrap) → **`D5/A3/C3/R3`**
|
||
|
||
| Dimension | Was (SCOPE 2026-06-22) | Now | Notes |
|
||
| --- | --- | --- | --- |
|
||
| Discovery | D4 | **D5** | INTENT, research, meta-framework spec, integration docs |
|
||
| Availability | A1 | **A3** | CLI + HTTP v0; CoulombCore remote smoke proven |
|
||
| Completeness | C1 | **C3** | Pillar 1–2 partial; pillars 3–4 (extensions breadth, payments) absent |
|
||
| Reliability | R1 | **R3** | Remote smoke, telemetry, stale inventory; no TTL auto-reap scheduler |
|
||
|
||
---
|
||
|
||
## 2. Workplan deliverables (cumulative)
|
||
|
||
| Workplan | Status | Key deliverable |
|
||
| --- | --- | --- |
|
||
| SAND-WP-0001 | finished | Python scaffold, AGENTS.md, dev workflow |
|
||
| SAND-WP-0002 | finished | Meta-framework, `ext.compose-ssh`, CLI, HTTP stub, registry |
|
||
| SAND-WP-0003 | finished | wise-validator sibling (`validate run`, schema/runner/reporter) |
|
||
| SAND-WP-0008 | finished | `profile.sandbox-canary`, telemetry, `inspect` / `reap-stale` |
|
||
|
||
---
|
||
|
||
## 3. INTENT — four pillars
|
||
|
||
### Pillar 1: Unified establishment API
|
||
|
||
| Capability | INTENT | Status | Gap |
|
||
| --- | --- | --- | --- |
|
||
| `create` / `get` / `list` / `destroy` / `recreate` | Required v0 | **Done** | CLI + HTTP |
|
||
| `extend_ttl` | API shape | **Stub only** | No implementation |
|
||
| `snapshot` / `restore` | Later completeness | **Absent** | SAND-WP-0007 |
|
||
| `active` state transition | Lifecycle | **Absent** | Optional; not wired |
|
||
| Consumer attribution | `adm`/`agt`/`atm` + project | **Done** | — |
|
||
| Full HTTP surface | Parallel to CLI | **Partial** | No `recreate`, host query param only on create |
|
||
|
||
### Pillar 2: Profile catalog
|
||
|
||
| Capability | INTENT | Status | Gap |
|
||
| --- | --- | --- | --- |
|
||
| `profile.compose-e2e` | Reference profile | **Done** | Remote-verified |
|
||
| `profile.sandbox-canary` | Self-dogfood | **Done** | SAND-WP-0008 |
|
||
| Agent-dev / health-probe profiles | Future consumers | **Absent** | glas-harness / wise-validator profiles |
|
||
| `ext.vm-packer` lineage | build-machines | **Absent** | SAND-WP-0005 |
|
||
| Registry + reuse-surface federation | Registry-first | **Draft only** | No `reuse-surface validate` publish |
|
||
| Setup metadata / secret refs | Blitzy pattern | **Schema only** | No resolution at provision boundary |
|
||
|
||
### Pillar 3: Extension platform
|
||
|
||
| Capability | INTENT | Status | Gap |
|
||
| --- | --- | --- | --- |
|
||
| `ext.compose-ssh` | First self-hosted | **Done** | podman-compose on CoulombCore |
|
||
| Extension SDK / author contract | Near-term outcome #7 | **Absent** | Documented in meta-framework only |
|
||
| vm-packer, Daytona OSS, OpenShell | Self-hosted class | **Absent** | SAND-WP-0005 |
|
||
| E2B, Modal, SaaS adapters | SaaS class | **Absent** | SAND-WP-0006 |
|
||
| `estimate_cost` optional hook | Extension interface | **Absent** | — |
|
||
| Routing policy engine | Multi-backend | **Deferred** | Explicit profile→extension today |
|
||
|
||
### Pillar 4: Payments and metering
|
||
|
||
| Capability | INTENT | Status | Gap |
|
||
| --- | --- | --- | --- |
|
||
| Credits / usage accounting | SaaS extensions | **Absent** | SAND-WP-0006 |
|
||
| BYOK for provider keys | SaaS | **Absent** | — |
|
||
| Self-hosted allocation metering | Host/duration | **Partial** | Telemetry deltas only; no billing export |
|
||
|
||
---
|
||
|
||
## 4. INTENT — governing principle (seven questions)
|
||
|
||
| # | Question | Status | Evidence / gap |
|
||
| --- | --- | --- | --- |
|
||
| 1 | Which sandbox recipe? | **Met** | Profile loader, two profiles |
|
||
| 2 | Which backend? | **Partial** | Single extension; no routing engine |
|
||
| 3 | Where does it run? | **Partial** | Placement env vars; sandboxer01 not live |
|
||
| 4 | How is isolation enforced? | **Partial** | Compose project isolation; network default-deny declarative only |
|
||
| 5 | How reachable? | **Partial** | SSH direct; ops-bridge/warden not integrated in descriptor |
|
||
| 6 | What happened? | **Met** | State Hub events + local store |
|
||
| 7 | What did it cost? | **Not met** | Payments layer absent |
|
||
|
||
**Score: 2 met, 4 partial, 1 not met**
|
||
|
||
---
|
||
|
||
## 5. Self-sufficiency and sibling boundaries
|
||
|
||
| Criterion | Status | Notes |
|
||
| --- | --- | --- |
|
||
| Operates without wise-validator | **Met** | `sandboxer create` / canary / smoke |
|
||
| wise-validator optional consumer | **Met** | SAND-WP-0003; one-way dependency documented |
|
||
| sand-boxer does not validate | **Met** | Health/test in wise-validator |
|
||
| glas-harness / snuggle-inventor contracts | **Partial** | Integration docs only; no consumer smoke |
|
||
| Monolith not recreated | **Met** | Provision vs validation split holds |
|
||
|
||
---
|
||
|
||
## 6. Near-term outcomes (INTENT § Near-term)
|
||
|
||
| # | Outcome | Status |
|
||
| --- | --- | --- |
|
||
| 1 | Charter and research | **Done** |
|
||
| 2 | First self-hosted extension | **Done** |
|
||
| 3 | Unified API v0 | **Done** |
|
||
| 4 | Profile catalog start | **Done** |
|
||
| 5 | Registry entry | **Done** (draft) |
|
||
| 6 | Sibling integration notes | **Done** |
|
||
| 7 | Extension SDK sketch | **Open** |
|
||
| 8 | wise-validator | **Done** (sibling repo) |
|
||
|
||
---
|
||
|
||
## 7. Maturity target gaps
|
||
|
||
| Maturity statement | Status | Track |
|
||
| --- | --- | --- |
|
||
| glas-harness requests sandboxes without backend choice | **Not yet** | Extension SDK + agent-dev profile |
|
||
| wise-validator may request validation environments | **Met** | `validate run` uses `profile.compose-e2e` |
|
||
| snuggle-inventor build sandboxes with setup metadata | **Not yet** | Secret boundary + profile inputs |
|
||
| activity-core / CI bounded venues + visibility | **Partial** | Lifecycle events; no activity-core wiring |
|
||
| Operators route self-hosted vs SaaS spend | **Not yet** | SAND-WP-0006 |
|
||
| Workstation optional for runtime | **Partial** | Remote path works; custodian shim still default for some |
|
||
|
||
---
|
||
|
||
## 8. SCOPE.md drift (corrected 2026-06-23)
|
||
|
||
| SCOPE claim (2026-06-22) | Actual state |
|
||
| --- | --- |
|
||
| "implementation not started" | v0 shipped |
|
||
| "Nothing in this repo provisions sandboxes" | `sandboxer create` provisions |
|
||
| "registry empty / helix_forge" | indexed `infotech` capability |
|
||
| "wise-validator migration not complete" | SAND-WP-0003 done |
|
||
| Interim `make e2e` only path | Still true until SAND-WP-0004 |
|
||
|
||
---
|
||
|
||
## 9. Remaining gaps (prioritized)
|
||
|
||
| Prio | Gap | Owner / repo | Proposed track |
|
||
| --- | --- | --- | --- |
|
||
| **P1** | `the-custodian` `make e2e REPO=` → `validate run` shim | the-custodian + wise-validator | **SAND-WP-0004** |
|
||
| **P2** | Extension SDK sketch + `ext.vm-packer` / build-machines | sand-boxer | **SAND-WP-0005** (INTENT near-term #7 + WP-0002 follow-on) |
|
||
| **P3** | TTL enforcement + `extend_ttl` + activity-core reap hook | sand-boxer + activity-core | New workplan after 0005 |
|
||
| **P5** | `.repo-classification.yaml` + reuse-surface validate | sand-boxer | Ad hoc or WP task |
|
||
| **P6** | Security runbook (blast-radius vs intent enforcement) | sand-boxer docs | Ad hoc |
|
||
| **P7** | sandboxer01 dedicated host + placement live | infra / operator | Outside repo |
|
||
| **P8** | SaaS extensions + payments | sand-boxer | **SAND-WP-0006** |
|
||
| **P9** | Snapshot / restore profiles | sand-boxer | **SAND-WP-0007** |
|
||
| **P10** | wise-validator remote smoke sign-off (T09) | wise-validator | Operator verification |
|
||
|
||
**Note:** SAND-WP-0002 follow-on numbering reserves 0004–0007. Next workplan should be
|
||
**SAND-WP-0004** (custodian shim) to close the e2e-framework migration arc.
|
||
|
||
---
|
||
|
||
## 10. Recommended next workplan
|
||
|
||
**SAND-WP-0004 — the-custodian e2e shim and deprecation**
|
||
|
||
Closes P1: operators keep `make e2e REPO=` while implementation delegates to
|
||
`validate run` (wise-validator + sand-boxer). Updates RUNBOOK pointers; adds
|
||
deprecation notice on `python -m e2e_framework`.
|
||
|
||
Subsequent: **SAND-WP-0005** (`ext.vm-packer` + extension SDK), then operational
|
||
hardening (TTL, reuse-surface publish).
|
||
|
||
---
|
||
|
||
## 11. Evidence references
|
||
|
||
- `workplans/SAND-WP-0002-meta-framework-foundation.md` (finished)
|
||
- `workplans/SAND-WP-0003-wise-validator-extraction.md` (finished)
|
||
- `workplans/SAND-WP-0008-host-telemetry-and-self-canary.md` (finished)
|
||
- `docs/migration-gaps.md`
|
||
- `wise-validator/docs/runbooks/validate-compose-e2e.md`
|
||
- CoulombCore smoke: `scripts/smoke-compose-e2e.sh` (SAND-WP-0002-T10) |