Phases E & F — Opportunities, Solutions & Migration Planning
What stands between today and the target, packaged into work; the transition architectures that are each individually useful; and the milestone plan with exit criteria that decide whether the next slice is worth building.
E1 · Gap analysisBaseline → target, and the work package that closes each gap
Baseline describes the common starting point in a large enterprise (and the empty state of the reference implementation). "Eliminated" rows are things the target deliberately removes.
| Area | Baseline (today) | Target | Gap | Closed by |
|---|---|---|---|---|
| Schema knowledge | Tribal; comments sparse; no join-path knowledge outside people's heads | Versioned semantic catalog with owner-reviewed cards, mined join paths, glossary | No catalog, no crawler, no review loop | WP02 · WP03 |
| Retrieval over schema | None, or schema pasted into prompts | Hybrid retrieval + graph expansion + entitlement pre-filter; cite-or-refuse | No index, no graph, no citation discipline | WP03 · WP05 |
| Use-case intake | Tickets in prose; requirements drift | Typed spec with archetypes and clarification loops | No spec schema, no archetype library | WP04 |
| API per use case | Hand-written endpoints or ad-hoc SQL; per-project security review | Generated GraphQL slices, policies on fields, composed into one supergraph | No composer, no registry, no policy directive discipline | WP06 · WP08 |
| Authorization | Post-filtering in application code; route-level rules | Entitlements compiled into SQL; deny-by-default fields; 100% coverage gate | No compiler, no policy catalog as data | WP07 · WP06 |
| Screens | Bespoke React per use case; backlog measured in quarters | Spec-driven runtime; ~12 components; reviewed escape hatch | No DSL, no runtime, no registry | WP09 · WP10 · WP15 |
| Verification | Manual QA; security review at the end | Nine deterministic gates in CI; sample sandbox | No gates, no sandbox, no golden sets | WP11 |
| Approval & publish | Email threads; releases as code deploys | Review workspace; release unit pinned; auto-publish rules for read-only re-publishes | No review UI, no release-unit concept | WP12 · WP14 |
| Writes | Direct writes from apps; approvals per app | Proposals; platform-enforced approval from registration | No proposal service | WP13 |
| Change | Schema changes break screens silently | Catalog versioning → automatic re-verification → degraded state | No drift detection, no re-verification | WP14 |
| Observability & cost | Per-app logs; model spend untracked | Traces per use case and run; cost attributed; budgets enforced | No trace model, no attribution | WP16 |
| Text-to-SQL for users | Pilots exist | eliminated | Replace with persisted operations only | WP08 (policy) |
| Generated apps per use case | Prototypes exist | eliminated | Replace with spec + registry | WP09 (policy) |
E2 · Work packagesSeventeen packages, each with a deliverable and a done-test
| WP | Deliverable | Done when | Depends on | Milestone |
|---|---|---|---|---|
| WP01 Scaled sample DB | Generator producing ≥3,000 tables across ~12 domains with FKs, comments (deliberately sparse), pathologies, synthetic volumes | Schema loads; row counts hit targets; pathology list present | — | M0 |
| WP02 Crawler & catalog | information_schema/comment/profile/query-log crawl → cards, join paths, versions; owner-review UI | Catalog #1 built; diff between two crawls correct | WP01 | M0 |
| WP03 Retrieval & join graph | Hybrid search, graph expansion, pruning, entitlement pre-filter | Subgraph precision/recall measured on 50 seeded requests | WP02 | M0 |
| WP04 Intake + supervisor | Spec schema, archetype library, XState supervisor, budgets, run log | Ambiguous request round-trips; budgets fail closed | — | M1 |
| WP05 Scout agent | Catalog tools, cited subgraph output, ambiguity events | Zero hallucinated tables across seeded set | WP03 · WP04 | M1 |
| WP06 Contract composer + policy gate | SDL generation, policy application, persisted operation set, coverage walker | 100% coverage on seeded slices; composition dry-run passes | WP05 · policy store | M2 |
| WP07 Query compiler + entitlements | Kysely compiler; predicate injection; null-on-deny; batching; cost check | Every op compiles scoped for every role; zero unscoped SQL in CI | WP06 | M2 |
| WP08 Registry + gateway + persisted docs | Hive registry, supergraph gateway, persisted document allow-list | Unknown op id rejected; breaking change blocks publish | WP06 | M2 |
| WP09 UI spec DSL + runtime | DSL schema, validator, React renderer, component registry (12 components) | Seeded spec renders every archetype; a11y lint passes | WP08 | M3 |
| WP10 UI composer | Spec generation bound to persisted ops; custom-component requests | First end-to-end screen from prose | WP09 | M3 |
| WP11 Verifier gates + sandbox | Nine gates; sample sandbox runner; golden test generator; PII scanner | Gate failure taxonomy populated; no auto-override path | WP07 · WP09 | M4 |
| WP12 Review workspace + publish | Evidence bundle, preview, approval routing, publish, registration rules | Reviewer approves a use case end to end; decision immutable | WP11 | M4 |
| WP13 Proposals | Proposal subgraph; status lifecycle; owning-system hand-off | Write path requires separate approval; no direct write exists | WP12 | M4 |
| WP14 Drift & release units | Catalog version events → re-verify → degraded state; release-unit pinning | Renamed column yields computed blast radius and pinned fallback | WP11 · WP12 | M5 |
| WP15 Escape-hatch pipeline | Sandboxed component build, allow-list, scan, screenshot diff, registry publish (federated) | Custom component reaches registry only via review | WP09 · WP11 | M5 |
| WP16 Observability & cost | OTel spans with use-case/run/op ids; cost attribution; budgets | Any screen's SQL reproducible from the trace | WP07 | M2 → M6 |
| WP17 Seeded use cases & metrics | 100 use cases across archetypes; minutes per use case, escape-hatch rate, gate taxonomy, reviewer throughput | §10 scaling claims measured, published with the caveats | all | M6 |
E3 · Transition architecturesFive states, each useful on its own
Each transition is a stopping point that delivers value even if the next never happens — the honest test of a roadmap.
Retrieval proven
Has: scaled sample DB, catalog, hybrid retrieval, join graph.
Useful as: a schema search and documentation tool for humans.
Proves: the model can be shown the right 30 tables.
Contracts publishable
Adds: intake, supervisor, Scout, contract composer, compiler, registry.
Useful as: generated, governed GraphQL APIs without UI.
Proves: authorization compiled into the query, at scale.
Screens, read-only
Adds: UI spec DSL, runtime, UI composer, gates, review, publish.
Useful as: on-demand read-only business screens.
Proves: minutes per use case; reviewer throughput.
Writes & drift
Adds: proposals, release units, drift re-verification, degraded state.
Useful as: actionable screens that survive schema change.
Proves: computed blast radius; no direct writes.
Scale & exceptions
Adds: escape-hatch pipeline, 100 seeded use cases, metrics, cost attribution.
Useful as: the reference implementation with published numbers.
Proves or disproves: the scaling claims.
F1 · Implementation & migration planMilestones M0 → M6 with exit criteria — each gate decides whether the next slice is built
M0 exit
Subgraph precision/recall on 50 seeded requests meets target; ambiguity rate recorded. If retrieval fails here, nothing else is worth building.
M1 exit
No hallucinated tables across the seeded set; ambiguous requests round-trip; budgets fail closed and park.
M2 exit
Every persisted operation compiles scoped for every actor role; zero unscoped SQL reachable; unknown op ids rejected at the gateway; breaking changes block publish.
M3 exit
First end-to-end screen from a prose request; every archetype renders from a seeded spec; accessibility lint passes.
M4 exit
A reviewer approves a use case with a write path end to end; gate failure taxonomy populated; no auto-override path exists.
M5 exit
A renamed column yields a computed list of affected use cases, automatic re-verification, and a pinned fallback; a custom component reaches the registry only via review.
M6 exit
100 seeded use cases: minutes per use case, escape-hatch rate, reviewer throughput, gate taxonomy, cost per use case — published with caveats.
Dependencies & risks
- Policy catalog quality gates M2 — classification coverage is a prerequisite
- LLM provider variance — pinned versions; golden sets catch regressions
- Review throughput — measured at M4, tuned at M6