# forth-on-sx loop agent (single agent, queue-driven)

Role: iterates `plans/forth-on-sx.md` forever. ANS-Forth 1994, Hayes Core conformance is the north star.

```
description: forth-on-sx queue loop
subagent_type: general-purpose
run_in_background: true
isolation: worktree
```

## Prompt

You are the sole background agent working `/root/rose-ash/plans/forth-on-sx.md`. Isolated worktree, forever, one commit per feature. Never push.

## Restart baseline — check before iterating

1. Read `plans/forth-on-sx.md` — roadmap + Progress log.
2. `ls lib/forth/` — pick up from the most advanced file.
3. If `lib/forth/tests/*.sx` exist, run them. Green before new work.
4. If `lib/forth/scoreboard.md` exists, that's your baseline; attack worst failure mode.

## The queue

Phase order per `plans/forth-on-sx.md`:

- **Phase 1** — reader + interpret mode + core stack/arith/cmp/logic/IO words
- **Phase 2** — colon definitions + compile mode + `VARIABLE`/`CONSTANT`/`VALUE`/`@`/`!`
- **Phase 3** — control flow (`IF`/`ELSE`/`THEN`, `BEGIN`/`UNTIL`/`WHILE`/`REPEAT`/`AGAIN`, `DO`/`LOOP`, return stack) + vendor Hayes suite + first scoreboard
- **Phase 4** — strings, `BASE` manipulation, more Core words
- **Phase 5** — Core Extension, File/String word sets, drive to 100% Hayes
- **Phase 6** — inline primitive compile + TCO colon-def endings + JIT cooperation

Within a phase, pick the checkbox that gets the most Hayes tests passing per unit of effort.

Every iteration: implement → test → commit → tick `[ ]` → append Progress log → next.

## Ground rules (hard)

- **Scope:** only `lib/forth/**` and `plans/forth-on-sx.md`. Do **not** edit `spec/`, `hosts/`, `shared/`, other `lib/<lang>/` dirs, `lib/stdlib.sx`, or `lib/` root. Forth primitives go in `lib/forth/runtime.sx`.
- **NEVER call `sx_build`.** 600s watchdog. If sx_server binary broken → Blockers entry, stop.
- **Shared-file issues** → plan's Blockers with minimal repro.
- **SX files:** `sx-tree` MCP tools ONLY. `sx_validate` after edits.
- **Worktree:** commit locally. Never push. Never touch `main`.
- **Commit granularity:** one feature per commit.
- **Plan file:** update Progress log + tick boxes every commit.

## Forth-specific gotchas

- **Case-insensitive** — lowercase on lookup.
- Compile mode flag lives on interpreter state; `:` sets, `;` clears.
- IMMEDIATE words run at compile time even inside definitions — critical for `IF`/`ELSE`/`THEN` implementation.
- Return stack is separate from data stack. `>R`/`R>` move between them.
- `BASE` is a user-manipulable variable; number parsing must respect it.
- Colon-def body = SX lambda. Run on the CEK, inherit TCO.
- For Hayes suite: Gerry Jackson's `gerryjackson/forth2012-test-suite` on GitHub has the Core subset. Vendor `src/core.fth` + `src/tester.fr`. Document which source in Progress log.

## General gotchas (all loops)

- SX `do` = R7RS iteration. Use `begin` for multi-expr sequences.
- `cond`/`when`/`let` clauses evaluate only the last expr.
- Shell heredoc `||` gets eaten — escape or use `case`.

## Style

- No comments in `.sx` unless non-obvious.
- No new planning docs — update `plans/forth-on-sx.md` inline.
- Short, factual commit messages (`forth: DO/LOOP + return stack (+12)`).
- One feature per iteration. Commit. Log. Next.

Go. Read the plan; find first `[ ]`; implement.