forth: DO/LOOP/+LOOP/I/J/LEAVE + return stack words (+16)

plans/forth-on-sx.md

@@ -71,8 +71,8 @@ Representation:
 ### Phase 3 — control flow + first Hayes tests green
 - [x] `IF`, `ELSE`, `THEN` — compile to SX `if`
 - [x] `BEGIN`, `UNTIL`, `WHILE`, `REPEAT`, `AGAIN` — compile to loops
-- [ ] `DO`, `LOOP`, `+LOOP`, `I`, `J`, `LEAVE` — counted loops (needs a return stack)
-- [ ] Return stack: `>R`, `R>`, `R@`, `2>R`, `2R>`, `2R@`
+- [x] `DO`, `LOOP`, `+LOOP`, `I`, `J`, `LEAVE` — counted loops (needs a return stack)
+- [x] Return stack: `>R`, `R>`, `R@`, `2>R`, `2R>`, `2R@`
 - [ ] Vendor John Hayes' test suite to `lib/forth/ans-tests/`
 - [ ] `lib/forth/conformance.sh` + runner; `scoreboard.json` + `scoreboard.md`
 - [ ] Baseline: probably 30-50% Core passing after phase 3
@@ -99,6 +99,22 @@ Representation:
 
 _Newest first._
 
+- **Phase 3 — `DO`/`LOOP`/`+LOOP`/`I`/`J`/`LEAVE` + return stack words (+16).**
+  Counted loops compile onto the same PC-driven body runner. DO emits an
+  enter-op (pops limit+start from data stack, pushes them to rstack) and
+  pushes a `{:kind "do" :back PC :leaves ()}` marker onto cstack. LOOP/+LOOP
+  emit a dict op (`:kind "loop"`/`"+loop"` with target=back-cell). The step
+  handler pops index & reads limit, increments, and either restores the
+  updated index + jumps back, or drops the frame and advances. LEAVE walks
+  cstack for the innermost DO marker, emits a `:kind "leave"` dict op with
+  a fresh target cell, and registers it on the marker's leaves list. LOOP
+  patches all registered leave-targets to the exit PC and drops the marker.
+  The leave op pops two from rstack (unloop) and branches. `I` peeks rtop;
+  `J` reads rstack index 2 (below inner frame). Added non-immediate
+  return-stack words `>R`, `R>`, `R@`, `2>R`, `2R>`, `2R@`. Nested
+  DO/LOOP with J tested; LEAVE in nested loops exits only the inner.
+  177/177 green.
+
 - **Phase 3 — `BEGIN`/`UNTIL`/`WHILE`/`REPEAT`/`AGAIN` (+9).** Indefinite-loop
   constructs built on the same PC-driven body runner introduced for `IF`.
   BEGIN records the current body length on `state.cstack` (a plain numeric