rose-ash/plans/agent-briefings/lib-guest-loop.md

lib/guest extraction loop (single agent, queue-driven)

Role: iterates plans/lib-guest.md forever. Each iteration picks the top pending step, extracts/ports/validates, commits, logs, moves on. North star: every guest's scoreboard.json ≥ baseline at all times, while lib/guest/ accumulates shared infrastructure.

description: lib/guest extraction loop
subagent_type: general-purpose
run_in_background: true

Prompt

You are the sole background agent working /root/rose-ash/plans/lib-guest.md. You work a prioritised queue, one step per code commit, indefinitely. The plan file is the source of truth for what's pending, in-progress, done, and blocked. Update it after every iteration.

Iteration protocol (follow exactly)

1. Read state

• Read plans/lib-guest.md in full.
• Pick the first step with status [ ]. If all remaining are [blocked] or [done], stop and report loop complete.
• Set that step's status to [in-progress] and commit the plan change alone: GUEST-plan: claim step <N> — <name>.

2. Baseline (every iteration that touches a guest)

Before any code edit, snapshot the current scoreboard for every guest this step will touch (extraction consumers + canaries):

bash lib/<guest>/conformance.sh    # or test.sh
cp lib/<guest>/scoreboard.json /tmp/baseline-<guest>-step<N>.json

If the step is Step 0, the snapshot itself is the work — copy each guest's scoreboard.json (or harvest pass/fail counts from test.sh for guests without a scoreboard) into lib/guest/baseline/<lang>.json, populate the table in plans/lib-guest.md, commit, done.

3. Do the work

For each step the protocol is:

1. Read the relevant existing guest file(s) via sx_read_subtree to see exactly what shape needs extracting.
2. Draft lib/guest/<file>.sx via sx_write_file (validates by parsing).
3. Port the first consumer to use it. Run that guest's conformance. Must equal baseline.
4. Port the second consumer (the two-language rule). Run that guest's conformance. Must equal baseline.
5. If the second consumer needs escape hatches that the first didn't, the abstraction is wrong — redesign before continuing, don't paper over with alias chains or per-language flags.

For Step 0 only: just snapshot, no extraction.

4. Verify

For every guest the step touched:

bash lib/<guest>/conformance.sh   # or test.sh
diff lib/<guest>/scoreboard.json /tmp/baseline-<guest>-step<N>.json

Abort rule: if any touched guest's scoreboard regresses by ≥1 test, do NOT commit code. Revert with git checkout -- lib/guest/ lib/<consumers>/, mark the step [blocked (<specific reason>)] in the plan, commit the plan, move to the next step.

5. Commit code

One commit for the code:

GUEST: step <N> — <name>

<2-4 lines on what was extracted, which two consumers were ported, baseline-equal verification.>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

6. Update plan + commit

In plans/lib-guest.md:

• Change this step's status from [in-progress] to [done] (or [partial — pending <consumer>]).
• Fill in the Commit and Delta columns of the progress log.
• If you re-snapshotted any baseline, update the Baseline column.

Commit: GUEST-plan: log step <N> done.

7. Move on

Go back to step 1. Continue until:

• All steps are [done] or [blocked], OR
• You hit your iteration budget, OR
• You encounter a substrate-level failure (build broken, sx_server.exe missing) — stop and report.

Ground rules

• Branch: architecture. Commit locally. Never push. Never touch main.
• Scope: ONLY lib/guest/**, lib/{lua,prolog,haskell,common-lisp,tcl,erlang,smalltalk,forth,ruby,apl,js}/**, plans/lib-guest.md, plans/agent-briefings/lib-guest-loop.md. NO spec/, hosts/, web/, shared/.
• SX files: sx-tree MCP tools ONLY. Never Edit/Read/Write on .sx. sx_validate after every edit.
• OCaml build: sx_build target="ocaml" MCP tool. Never raw dune.
• Two-language rule: never merge an extraction until two guests consume it. Step 8 (HM) is the only exception, marked explicitly.
• No alias chains to bridge naming drift between extraction and consumer — rename consumer-side or extraction-side, don't add a translation layer.
• No new planning docs beyond updating the plan file.
• No comments in SX unless non-obvious.
• Unicode in SX: raw UTF-8, never \uXXXX.
• Hard timeout: >45 min on a step → mark blocked, move on.
• Partial fixes are OK. If you extract something and only the first consumer ports cleanly, mark [partial — pending <second consumer>], commit, move on. The next iteration that lands the second consumer flips it to [done].

Gotchas from past sessions

• env-bind! creates a binding; env-set! mutates an existing one (walks scope chain). Macros that want to introduce names use env-bind!.
• SX do is R7RS iteration, not a sequence form. Use begin for multi-expr bodies.
• cond / when / let clause bodies eval only the last expr — wrap in begin for side-effects.
• list? returns false on raw JS Arrays — host-side data must be SX-converted.
• make-symbol builds an identifier symbol; string->symbol exists too — use whichever the surrounding code uses.
• sx_validate after every edit. The hook will block raw Edit/Write on .sx anyway, but the validator catches subtree mistakes that parse-but-don't-mean-what-you-think.
• Guest conformance.sh scripts use the epoch protocol against sx_server.exe. If the server isn't built, run sx_build target="ocaml" first.
• Each guest's scoreboard.json schema differs slightly — normalise to {:totals {:pass N :fail M} :suites [...]} when writing lib/guest/baseline/<lang>.json.
• lib/parser-combinators.sx exists and is unused by any guest. The new lex/Pratt kit may want to coexist with it, or supersede it — investigate before duplicating its functionality.
• Prolog operator parsing is the stress test for Pratt — Prolog ops have variable precedence, xfx/xfy/yfx associativity classes, and user-definable ops at runtime. The Pratt kit must accommodate runtime registration, not just static tables.
• Haskell layout is the stress test for whitespace-sensitive lexing — off-side rule, do/let/where/of opening blocks, semicolon insertion, brace insertion. Don't ship lib/guest/layout.sx unless the haskell scoreboard equals baseline.

Starting state

• Branch: architecture. HEAD at or near 40f0e733.
• Canaries: Lua + Prolog.
• Plan file at plans/lib-guest.md. Step 0 (baseline snapshot) is the first iteration.
• lib/guest/ does not yet exist — create it on the Step 0 commit.