Document post-beta roadmap

.llm/ROADMAP_TO_STABLE.md

@@ -13,11 +13,21 @@ Slovo reaches stable `1.0.0` only after:
 
 ## Recommended Sequence
 
-1. Harden monorepo release tooling, clean docs, and public install/build flow.
-2. Stabilize `lib/std` module boundaries and document beta-vs-stable APIs.
-3. Broaden numeric completeness with explicit `f32` and additional integer
-   policy where needed.
-4. Improve collection and string breadth without exposing unstable ABI details.
+The detailed post-beta feature plan lives in
+`docs/POST_BETA_ROADMAP.md`. Keep this file as the short stable-readiness
+summary and use the public roadmap document when choosing the next connected
+implementation scope.
+
+1. Harden monorepo release tooling, install flow, and common build/run loops.
+2. Define runtime resource and host-error policy before broad IO and networking.
+3. Stabilize `lib/std` module boundaries and document beta-vs-stable APIs.
+4. Improve language usability around entry points, `match`, aliases, and
+   concrete numeric completeness.
 5. Expand package/workspace discipline before remote registry work.
-6. Add editor-facing diagnostics and generated documentation improvements.
-7. Freeze migration/deprecation policy and cut stable only after beta feedback.
+6. Add networking only after resource/error policy is coherent.
+7. Add serialization/data-interchange helpers before richer network libraries.
+8. Design generics and collection unification from real stdlib duplication
+   pressure.
+9. Add editor-facing diagnostics, watch mode, and generated documentation
+   improvements.
+10. Freeze migration/deprecation policy and cut stable only after beta feedback.

README.md

@@ -77,6 +77,7 @@ SLOVO_STD_PATH="$PWD/lib/std" ./compiler/target/debug/glagol build hello -o hell
 - [Language Manifest](docs/language/MANIFEST.md)
 - [Language Specification](docs/language/SPEC-v1.md)
 - [Compiler Manifest](docs/compiler/GLAGOL_COMPILER_MANIFEST.md)
+- [Post-Beta Roadmap](docs/POST_BETA_ROADMAP.md)
 - [Slovo Whitepaper](docs/papers/SLOVO_WHITEPAPER.md)
 - [Glagol Whitepaper](docs/papers/GLAGOL_WHITEPAPER.md)
 

docs/POST_BETA_ROADMAP.md

@@ -0,0 +1,202 @@
+# Post-Beta Roadmap
+
+Slovo `1.0.0-beta` is the first usable general-purpose beta baseline. The next
+work should broaden the language and toolchain in connected beta slices without
+pretending that ABI, package, runtime, or standard-library contracts are stable
+yet.
+
+## Direction
+
+The best continuation is not a single feature lane. Slovo needs alternating
+language, compiler, runtime, stdlib, and tooling slices so each new capability
+can be used in real programs and verified by the release gate.
+
+Each slice should ship only when it updates:
+
+- language and compiler docs
+- source examples and standard-library modules when relevant
+- formatter behavior
+- diagnostics and negative tests
+- hosted runtime behavior when relevant
+- benchmarks or conformance tests when relevant
+- release notes and the public roadmap
+
+## Immediate Sequence
+
+### 1. Tooling And Release Hardening
+
+Goal: make the public monorepo easy to build, test, install, and verify.
+
+Work:
+
+- add `glagol run` for the common build-and-execute loop
+- add `glagol clean` for generated build artifacts
+- improve `glagol new` templates for library, binary, and workspace projects
+- document install paths for `glagol`, `runtime/`, and `lib/std`
+- make release gates print a concise final summary
+- keep PDF rendering explicit and non-mutating by default
+
+Why first: it reduces friction for every later feature and gives users a better
+way to exercise the beta.
+
+### 2. Runtime And Resource Foundation
+
+Goal: create a safer foundation for host resources before adding networking or
+larger IO APIs.
+
+Work:
+
+- define beta resource-handle policy for files, processes, sockets, and future
+  host objects
+- make host errors consistently return concrete `result` values where possible
+- audit allocation failure behavior for strings and vectors
+- add runtime conformance tests for cleanup paths
+- document that resource handles are beta values, not stable ABI promises
+
+Why second: networking, file IO, process IO, and HTTP all need a common story
+for handles, errors, cleanup, and platform variance.
+
+### 3. Standard Library Stabilization Pass
+
+Goal: make existing `lib/std` modules feel coherent before adding many new
+surface areas.
+
+Work:
+
+- mark each public helper as beta-supported, experimental, or internal
+- normalize naming across `std.string`, `std.num`, `std.math`, `std.io`,
+  `std.fs`, `std.env`, `std.process`, `std.cli`, `std.time`, and `std.random`
+- add examples that compose multiple modules in one realistic command-line
+  program
+- add stdlib documentation generation coverage
+- identify helpers that should wait for generics instead of being copied across
+  concrete type families
+
+Why third: stdlib growth is already broad enough that naming and stability tiers
+matter more than adding another isolated helper group.
+
+### 4. Language Usability Slice
+
+Goal: reduce awkwardness in common programs without destabilizing the typed core.
+
+Candidate features:
+
+- `glagol run`-friendly `main` conventions and clearer entry-point diagnostics
+- better `match` diagnostics and exhaustiveness checks where the current enum
+  model allows it
+- type aliases for long concrete types such as vectors, options, and results
+- destructuring for simple structs and enum payloads
+- additional numeric completeness such as `f32`, only if it can be tested across
+  checker, formatter, runtime, and docs
+
+Why fourth: these features improve real Slovo code while keeping generics and
+traits deferred until the core has more feedback.
+
+### 5. Package And Workspace Discipline
+
+Goal: make multi-package local development predictable before remote registry
+work.
+
+Work:
+
+- document package identity, version, and local dependency rules
+- decide whether a lockfile belongs in the beta package model
+- add project-wide `fmt`, `check`, `test`, `doc`, `build`, and `run` behavior
+- add diagnostics for ambiguous package roots and dependency cycles
+- keep remote registry, semver solving, and publishing out of scope
+
+Why fifth: stable package rules are a prerequisite for a usable public language,
+but remote publishing can wait.
+
+### 6. Networking Foundation
+
+Goal: add minimal blocking local networking after resource and error policy is
+in place.
+
+Work:
+
+- add `std.net` with blocking TCP client/server primitives
+- use loopback-only deterministic tests
+- expose host failures through result values
+- keep TLS, async, DNS policy, HTTP server frameworks, and event loops deferred
+- add small examples such as echo client/server or local request/response
+
+Why sixth: networking is useful, but doing it before resources and host errors
+would create unstable API debt.
+
+### 7. Serialization And Data Interchange
+
+Goal: make Slovo useful for command-line and network programs without requiring
+maps/sets immediately.
+
+Work:
+
+- add string scanning/tokenizing helpers
+- add simple JSON text construction helpers first
+- defer full JSON object parsing until maps, richer strings, or generic
+  collections exist
+- add benchmark cases for parsing and formatting
+
+Why seventh: networking and CLI tools need data interchange, but a complete JSON
+library depends on collection work.
+
+### 8. Generics And Collection Unification
+
+Goal: stop duplicating every helper across concrete vector, option, and result
+families.
+
+Work:
+
+- design generic function syntax and typed-core representation
+- gate generic stdlib helpers behind conformance tests
+- migrate repeated concrete helpers only after compatibility policy is written
+- add generic arrays/vectors first, then maps and sets
+- keep stable ABI/layout promises deferred until after real beta use
+
+Why eighth: generics are important, but they should be introduced after the
+compiler, docs, tests, and stdlib have enough real pressure to validate the
+design.
+
+### 9. Developer Experience
+
+Goal: make Slovo comfortable for repeated daily use.
+
+Work:
+
+- language-server diagnostics and document symbols
+- project watch mode
+- generated API documentation for local packages and `lib/std`
+- clearer benchmark harness output
+- machine-readable diagnostics stability policy
+
+Why ninth: editor support matters, but it should follow a stable enough syntax,
+project model, and diagnostic model.
+
+## Stable `1.0.0` Gate
+
+Slovo should not become stable until all of these are true:
+
+- migration and deprecation policy is documented
+- `lib/std` has explicit stable and experimental tiers
+- package/workspace behavior is deterministic
+- conformance tests cover user-shaped projects
+- release gates are reproducible on a clean checkout
+- diagnostics and formatter output are stable for promoted features
+- performance publications are repeatable and labeled as local-machine evidence
+- the language can build useful local CLI tools, libraries, file-processing
+  programs, and basic host-interaction programs without undocumented behavior
+
+## Explicitly Deferred
+
+These should not be early post-beta work unless a smaller prerequisite slice is
+complete first:
+
+- full async runtime
+- TLS and certificate policy
+- remote package registry
+- macro system
+- stable C ABI/layout guarantees
+- optimizing compiler claims
+- web framework or HTTP server framework
+- broad Unicode/string normalization policy
+

docs/compiler/ROADMAP.md

@@ -1,6 +1,7 @@
 # Glagol Roadmap
 
-Glagol is the first compiler for Slovo. Slovo language design lives in `../language`.
+Glagol is the first compiler for Slovo. Slovo language design lives in
+`docs/language/` inside the same monorepo.
 
 Compiler rule: make the tree visible. The pipeline should remain:
 

docs/language/ROADMAP.md

@@ -1,7 +1,7 @@
 # Slovo Roadmap
 
-This roadmap tracks the language contract. Glagol, in `../glagol`, tracks the
-compiler implementation.
+This roadmap tracks the language contract. Glagol, in `compiler/`, tracks the
+compiler implementation inside the same monorepo.
 
 Guiding rule: the manifest wins. A feature is not accepted until it has surface syntax, typed-core meaning, lowering behavior, formatter behavior, diagnostics, and tests.