Merge chore/docs-reorg: reorganize docs into spec/architecture/ledgers/development/planning

Author: olwang

README.md

@@ -208,7 +208,7 @@ The product core is the review protocol: `.rssi` semantic contracts, structured
 
 Before AI, writing code was expensive and reviewing was manageable. That ratio has flipped: generating is cheap, reviewing is the bottleneck. RSScript is designed for the new ratio: AI writes, the compiler checks semantic boundaries, humans focus on the *risk*. What mutates, what gets retained, who owns a resource, where you cross into native or unsafe, what changed in a public API — all of it lives in the signature and in machine-readable diagnostics.
 
-This discipline is binding, not aspirational: the language specification opens with a [Constitution](docs/RSScript_v0.7_Spec.md#constitution) of nine articles that govern every design decision — most importantly that constraint is the product, that review-critical behavior must be explicit in the signature, and that a feature is admitted only if it phrases as a reviewer question and needs no implicit rule to be ergonomic. Restraint is anchored to a measurable property (review cost), which is what keeps it from eroding as the language grows.
+This discipline is binding, not aspirational: the language specification opens with a [Constitution](docs/spec/RSScript_v0.7_Spec.md#constitution) of nine articles that govern every design decision — most importantly that constraint is the product, that review-critical behavior must be explicit in the signature, and that a feature is admitted only if it phrases as a reviewer question and needs no implicit rule to be ergonomic. Restraint is anchored to a measurable property (review cost), which is what keeps it from eroding as the language grows.
 
 ---
 
@@ -404,7 +404,7 @@ RSScript source
 
 RSScript owns the review-facing front end: syntax, semantic checks, effects, managed/local/resource rules, diagnostics, review metadata, source mapping, and core/standard-package signatures. Rust owns everything below: codegen, optimization, platform support, linking, the crate ecosystem.
 
-This makes RSScript a review-first source format with a deliberately borrowed backend. The value is in the semantic protocol; the back end is Rust's strongest territory, and RSScript leans into that strength. Module boundaries are tracked in [ARCHITECTURE.md](docs/ARCHITECTURE.md).
+This makes RSScript a review-first source format with a deliberately borrowed backend. The value is in the semantic protocol; the back end is Rust's strongest territory, and RSScript leans into that strength. Module boundaries are tracked in [ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md).
 
 ---
 
@@ -509,9 +509,9 @@ fn main() -> Unit {
 }
 ```
 
-Development discipline and the full local verification flow live in [DEVELOPMENT.md](docs/DEVELOPMENT.md): spec prerequisites first, self-hosted validation as the main pressure test, no fixture-only shortcuts, and a broad-first testing loop.
+Development discipline and the full local verification flow live in [DEVELOPMENT.md](docs/development/DEVELOPMENT.md): spec prerequisites first, self-hosted validation as the main pressure test, no fixture-only shortcuts, and a broad-first testing loop.
 
-Prefer a containerized toolchain? [DOCKER.md](docs/DOCKER.md) gives an identical, reproducible build/test environment on macOS, Windows, and Linux (and VS Code / Codespaces) with no local Rust install:
+Prefer a containerized toolchain? [DOCKER.md](docs/development/DOCKER.md) gives an identical, reproducible build/test environment on macOS, Windows, and Linux (and VS Code / Codespaces) with no local Rust install:
 
 ```sh
 docker compose build

crates/reir/tests/reir_tests.rs

@@ -1229,7 +1229,7 @@ fn mvp_cross_layer_capability_reconciliation() {
 
 #[test]
 fn reir_spec_lists_implemented_core_slice_kinds() {
-    let spec = fs::read_to_string(workspace_root().join("docs/Review_Evidence_IR_Spec_v0.2.md"))
+    let spec = fs::read_to_string(workspace_root().join("docs/spec/Review_Evidence_IR_Spec_v0.2.md"))
         .expect("REIR spec should be readable");
     for kind in [
         "missing_capability_slice",
@@ -1271,7 +1271,7 @@ fn reir_spec_lists_implemented_core_slice_kinds() {
 
 #[test]
 fn reir_spec_lists_implemented_core_capability_categories() {
-    let spec = fs::read_to_string(workspace_root().join("docs/Review_Evidence_IR_Spec_v0.2.md"))
+    let spec = fs::read_to_string(workspace_root().join("docs/spec/Review_Evidence_IR_Spec_v0.2.md"))
         .expect("REIR spec should be readable");
     for category in [
         "network.client",
@@ -1320,7 +1320,7 @@ fn reir_spec_lists_implemented_core_capability_categories() {
 
 #[test]
 fn reir_spec_lists_implemented_core_fact_and_edge_kinds() {
-    let spec = fs::read_to_string(workspace_root().join("docs/Review_Evidence_IR_Spec_v0.2.md"))
+    let spec = fs::read_to_string(workspace_root().join("docs/spec/Review_Evidence_IR_Spec_v0.2.md"))
         .expect("REIR spec should be readable");
     for kind in [
         "capability",
@@ -1402,7 +1402,7 @@ fn reir_spec_lists_implemented_core_fact_and_edge_kinds() {
 
 #[test]
 fn reir_spec_lists_implemented_core_subject_kinds() {
-    let spec = fs::read_to_string(workspace_root().join("docs/Review_Evidence_IR_Spec_v0.2.md"))
+    let spec = fs::read_to_string(workspace_root().join("docs/spec/Review_Evidence_IR_Spec_v0.2.md"))
         .expect("REIR spec should be readable");
     for kind in [
         "application",

crates/rsscript/tests/checker_package/review.rs

@@ -1453,7 +1453,7 @@ build_execution_default = "sometimes"
 #[test]
 fn reir_spec_keeps_os_close_as_descriptor_cleanup_not_external_capability() {
     let root = common::workspace_root();
-    let spec = fs::read_to_string(root.join("docs/Review_Evidence_IR_Spec_v0.2.md"))
+    let spec = fs::read_to_string(root.join("docs/spec/Review_Evidence_IR_Spec_v0.2.md"))
         .expect("REIR spec should be readable");
 
     assert!(spec.contains("`OS.close`"));

crates/rsscript/tests/common/mod.rs

@@ -47,7 +47,7 @@ pub fn package_manager_spec_path() -> PathBuf {
 /// Find exactly one file in `docs/` whose name starts with `prefix` and ends
 /// with `suffix` (the span between them is the version and is not constrained).
 fn find_versioned_doc(prefix: &str, suffix: &str) -> PathBuf {
-    let docs = workspace_root().join("docs");
+    let docs = workspace_root().join("docs").join("spec");
     let mut matches: Vec<PathBuf> = fs::read_dir(&docs)
         .unwrap_or_else(|error| panic!("docs/ should be readable: {error}"))
         .filter_map(|entry| entry.ok().map(|entry| entry.path()))

crates/vm-jit/src/lib.rs

@@ -1,5 +1,5 @@
 //! Native (Cranelift) baseline JIT for the RSScript register VM's numeric /
-//! boolean / control-flow core — Phase 2 of `docs/jit-roadmap.md`.
+//! boolean / control-flow core — Phase 2 of `docs/architecture/jit-roadmap.md`.
 //!
 //! # What it compiles
 //!

docs/README.md

@@ -2,27 +2,46 @@
 
 Normative specifications and design drafts for RSScript. The project root keeps
 only `README.md` (overview) and `AGENT.md` (the prompt-sized language guide for
-LLMs); everything else lives here.
+LLMs); everything else lives here, grouped into categorized subfolders.
 
-## Normative specs
+## Spec
 
 | Doc | What it governs |
 |-----|-----------------|
-| [RSScript_v0.7_Spec.md](RSScript_v0.7_Spec.md) | The language. Opens with a binding **Constitution** (Articles I–IX) that overrides every chapter. |
-| [RSScript_Package_Manager_Design_v0.6.md](RSScript_Package_Manager_Design_v0.6.md) | The package manager (`rss pkg`): `.rssi` contracts, `rsspkg.toml`/`.lock`, semantic dependency review. |
-| [Review_Evidence_IR_Spec_v0.2.md](Review_Evidence_IR_Spec_v0.2.md) | REIR — the review-evidence IR consumed by `--reir` tooling and CI gates. |
-| [ARCHITECTURE.md](ARCHITECTURE.md) | Module boundaries of the checker/lowering implementation. |
-| [DEVELOPMENT.md](DEVELOPMENT.md) | Local verification flow and development discipline. |
-| [DOCKER.md](DOCKER.md) | Containerized, cross-platform dev environment (Docker / VS Code / Codespaces). |
-| [spec-todo.md](spec-todo.md) | Prioritized list of unimplemented spec surface (the §3.2 / §20.1 superset). |
-| [cross-isolate-design.md](cross-isolate-design.md) | Feasibility + smallest-sound-slice plan for the cross-isolate message API (§20.2-3): message-channel core landed, multi-heap isolates still future. |
-| [ml-perf-todo.md](ml-perf-todo.md) | ML-framework perf plan: native tensor kernels (fix VM big-matrix cliff) + AOT build-time levers. |
-
-## Implementation-planning specs (not yet normative)
+| [RSScript_v0.7_Spec.md](spec/RSScript_v0.7_Spec.md) | The language. Opens with a binding **Constitution** (Articles I–IX) that overrides every chapter. |
+| [RSScript_Package_Manager_Design_v0.6.md](spec/RSScript_Package_Manager_Design_v0.6.md) | The package manager (`rss pkg`): `.rssi` contracts, `rsspkg.toml`/`.lock`, semantic dependency review. |
+| [Review_Evidence_IR_Spec_v0.2.md](spec/Review_Evidence_IR_Spec_v0.2.md) | REIR — the review-evidence IR consumed by `--reir` tooling and CI gates. |
+
+## Architecture
+
+| Doc | What it governs |
+|-----|-----------------|
+| [ARCHITECTURE.md](architecture/ARCHITECTURE.md) | Module boundaries of the checker/lowering implementation. |
+| [vm-architecture.md](architecture/vm-architecture.md) | Register VM design: bytecode, dispatch, and runtime layout. |
+| [jit-roadmap.md](architecture/jit-roadmap.md) | Phased plan for the native (Cranelift) baseline JIT. |
+
+## Ledgers
+
+| Doc | What it governs |
+|-----|-----------------|
+| [jit-semantics-ledger.md](ledgers/jit-semantics-ledger.md) | Per-op record of JIT/VM semantic parity decisions. |
+| [rss-selfhost-ledger.md](ledgers/rss-selfhost-ledger.md) | Self-hosting progress ledger for the RSScript-in-RSScript toolchain. |
+
+## Development
+
+| Doc | What it governs |
+|-----|-----------------|
+| [DEVELOPMENT.md](development/DEVELOPMENT.md) | Local verification flow and development discipline. |
+| [DOCKER.md](development/DOCKER.md) | Containerized, cross-platform dev environment (Docker / VS Code / Codespaces). |
+
+## Planning
 
 | Doc | Idea |
 |-----|------|
-| [RSScript_AI_Generation_Feedback_v0.1.md](RSScript_AI_Generation_Feedback_v0.1.md) | Agent-facing generation oracle plus fast interpreter feedback loop for AI-generated RSScript. |
+| [spec-todo.md](planning/spec-todo.md) | Prioritized list of unimplemented spec surface (the §3.2 / §20.1 superset). |
+| [ml-perf-todo.md](planning/ml-perf-todo.md) | ML-framework perf plan: native tensor kernels (fix VM big-matrix cliff) + AOT build-time levers. |
+| [cross-isolate-design.md](planning/cross-isolate-design.md) | Feasibility + smallest-sound-slice plan for the cross-isolate message API (§20.2-3): message-channel core landed, multi-heap isolates still future. |
+| [RSScript_AI_Generation_Feedback_v0.1.md](planning/RSScript_AI_Generation_Feedback_v0.1.md) | Agent-facing generation oracle plus fast interpreter feedback loop for AI-generated RSScript. |
 
 ## Conventions