rose-ash/plans/agent-briefings/forth-loop.md

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.