epic: Road to 0.0.1-stable

[rickylabs]

Program epic tracking everything between 0.0.1-alpha.19 and a credible 0.0.1-beta.x, then 0.0.1-stable. Supervised by the road-to-stable program session; the coordinator holds the merge gate.

Locked positioning

NetScript competes on AI-agent build-efficiency, not runtime throughput. Defensible falsifiable claim: one-primitive-per-concern + compile-time contract enforcement + explicit plugin composition let an AI agent ship production-grade backend code in fewer turns with less hand-rolled code than bare routers, and at production-readiness parity-or-better vs the batteries-included tier (Encore.ts). This sidesteps the RPS fight and plays where the evidence is winnable. Falsifiable via turns_to_green + production_rubric_pass_rate (t1/t2), low-variance test_pass_rate (t1), and a reactive Fresh-UI task (t3b) as a separate extended axis. We do not claim shipped AI-backend capability (in-flight #238), throughput leadership, or API stability yet. Credibility asset: fork Encore's exact weights, publish raw traces, disclose the alpha-corpus + Fresh-2-beta confounds openly. Source: validated netscript-bench-research.v2.md.

Locked acceptance criteria (bench numbers = post-Run-1 "match-or-beat peer median" placeholders)

0.0.1-beta.x — correctness floor + repo maturity

• Self-bench exists; Run-1 t1+t2 test_pass_rate >= 0.90 median; t1 turns_to_green <= NestJS median; t1 production_rubric >= 0.50; zero harness-level NetScript failures.
• e2e-cli-prod + scaffold.runtime green (hard gates); plugin-service type-soundness fixed (172a-2-SOUND); public surface doc-linted; zero machine-specific assumptions in shipped tooling; doctrine v2 ratified with fitness functions in arch:check; stale-elimination wave-1 complete; one-shot deterministic release:cut proven by cutting the beta itself.

0.0.1-stable — leadership + production-readiness

• t2 turns_to_green strictly below all bare routers and <= Encore.ts; production_rubric >= 0.80 and test_pass_rate >= 0.95 on t1-t3; composite top-2 among core-5; reproduced across Sonnet 5 + Opus 4.8; t3b >= 0.90.
• Full cross-framework batch published; continuous self-bench per release; API/semver policy + public-surface-diff CI gate; deprecation policy enforced; >=1 verified production deployment path + CI deployability gate; zero unowned arch-debt.

Children (sub-epics)

• [S1] Positioning + netscript-bench #302 — S1 Positioning + netscript-bench
• [S2] Enterprise maturation + consolidation #303 — S2 Enterprise maturation + consolidation
• [S3] De-rickylabs / machine-agnostic tooling #304 — S3 De-rickylabs / machine-agnostic tooling (closed 2026-07-03)
• [S4] Architecture Doctrine revamp #305 — S4 Doctrine revamp
• [S5] Harness + skills revamp #306 — S5 Harness + skills revamp
• [S6] Stale-code + stale-file elimination #307 — S6 Stale-code + stale-file elimination
• epic: NetScript enterprise deployment framework (cloud-agnostic + bare-metal, CLI + Aspire) #327 — S7 Deployment (dedicated Deployment Fable epic, now filed & unblocked; child of this umbrella, not owned or designed here). SERVY verdict = MODERNIZE; tier-1 beta targets = Deno Deploy + deno compile bare-metal + Docker/Compose; Aspire container/cloud lane critical-path-gated on ada2a5 AddDenoApp seam Layer B tracking: Aspire Deno hosting (AddDenoApp / DenoAppResource) #320 (Phases 0–2 unblocked). Satisfies the stable milestone's "≥1 verified production deployment path + CI deployability gate." Supersedes the [S7] Deployment (tracking pointer → dedicated Deployment epic) #308 tracking pointer.
• [S8] Release engineering + API-stability gates #309 — S8 Release engineering + API-stability gates
• epic: migrate NetScript DB layer to Prisma Next (Postgres-first pilot, deferred) #313 — DB-layer foundation: Prisma-Next migration (deferred; spec + gap-tracker only, impl deferred; Postgres-first additive pilot, multi-db guarantee holds, MSSQL stays classic path). Tracked child with a locked design — NOT a beta blocker. Gap sub-issues: Prisma Next gap (a): MSSQL support (absent & unplanned) #314 MSSQL · Prisma Next gap (b): shipped Standard-Schema validator consumer #315 Standard-Schema validator consumer (Zod-deletion unlock) · Prisma Next gap (c): MySQL engine (planned, no date) #316 MySQL · Prisma Next gap (d): Turso/libsql driver (absent) #317 Turso/libsql · Prisma Next gap (e): beta/GA channel promotion off Early Access #318 beta/GA channel.
• epic: beta.3 → stable roadmap re-forecast #391 — beta.3→stable re-forecast epic (roadmap-expansion seed run; milestone train authority)
• epic: telemetry-revamp — framework telemetry convention + ports/adapters + dashboard query surface (Spine-1 enabler) #399 — telemetry-revamp epic (T1–T9; beta.5 slice = [telemetry T1] Framework telemetry convention (TC-1..14) + attribute-namespacing law #402/[telemetry T2] Package ports/adapters restructure (close Refactor arch-debt) #403, remainder beta.6)
• epic: NetScript Dev Dashboard — the Aspire/Scalar satellite that drives the framework (ships as a plugin, beta.6) #400 — Dev Dashboard epic (beta.6; DDX-8 co-lands with telemetry T4–T7)
• epic: beta.7 docs release cut — tutorial rewrites + per-feature positioning #401 — docs-cut epic (beta.7)

Tracked in-flight lanes (owned elsewhere — referenced, not stomped)

• Docs-site quality overhaul: epic: docs — march to 0.0.1-stable (coverage & accuracy) #232 / docs/DX: TypeScript AppHost model — restart semantics, hand-edit-vs-regen, service→plugin references, native-driver permissions #264 / AI stack (docs capstone): full docs-site coverage + simplified eis-chat tutorial #278 (owns all docs authoring; doc gaps route there). Handed-off follow-ups tracked here: Group A — Storefront tutorial Run-2 (release-cut-gated, Refs 🔬 Tutorial DX Eval (alpha.17, ARMED): lock criteria + track 4 tutorial runs + derived backlog #153); Group B — how-to/customize-fresh-ui.md prompt-input/dropzone copy refresh (enhancement).
• AI stack: epic: NetScript AI Stack — first-class AI runtime, chat & plugin seams (anchor #219) #238 (converging; consolidate as it lands, do not re-architect mid-flight)
• Aspire Deno-runtime proof: Dogfood proof: Aspire Deno runtime (Layers A+B) verified against the full NetScript framework #295 (evidence-only)
• DB layer: owned by child epic epic: migrate NetScript DB layer to Prisma Next (Postgres-first pilot, deferred) #313 (Prisma-Next migration) — carved out of every stale/maturation sweep; any DB-layer finding routes to epic: migrate NetScript DB layer to Prisma Next (Postgres-first pilot, deferred) #313, never edited inline here.
• GitHub-native process layer (milestones/RFC/templates/labels/Projects/Discussions/community-health — owned by a dedicated process lane)

Operating rules

Focused reviewable PRs only, never a mega-PR. Every branch cuts from origin/main (the working checkout ran 380 commits behind during audit). Doctrine-first for packages//plugins/; contract-first; wrap-don't-reinvent. Implementer and evaluator are separate sessions; CI quality trio (fmt:check+lint+check, workspace check needs --unstable-kv) reproduced before every PR; scaffold-affecting changes run deno task e2e:cli run scaffold.runtime --cleanup --format pretty. e2e-cli-prod stays a hard release gate. Publishing stays in CI via OIDC. No backward-compat pre-beta: stale code is deleted, not shimmed.

Stale-elimination methodology note (S6/#307)

Deleting a .css/asset file requires a class-name-coupling check (does any shipped component apply the BEM/selectors it defines via cn(...)/class=?), not only an @import/<link>/registry-import grep. Wave-1 nearly dropped fresh-ui/src/presentation/data-grid.css, which styles the shipped exported DataGrid (#225) purely by ns-data-grid* class-name coupling — invisible to import-grep and to deno check (CSS is not type-checked). Restored before merge (PR #324).

User decisions pending (bench §12)

D1 VM provider · D2 framework list · D3 task count · D4 score weights · D5 model+cadence · D6 repo location · D7 license. Plus product escalations: beta/stable version-surface strategy; --legacy-aspire removal approval; packages/runtime-config roadmap-or-retire. From #313 (DB layer, coordinator-held): default-flip policy · Postgres-only-vs-all-engines matrix policy · validator-branch confirmation. NetScript self-bench proceeds without any of these.