phase1 formulate: scope, tech decisions, module changes, open questions
Inner-loop Phase 1 (formulate) deliverable for the milestone Phase 1 of
the aish project. Drafts docs/PHASE1.md to specify what lands on top of
the Phase 0 substrate — no code changes, no §3 invariant amendments.
Phase 1 milestone scope per PHASE0.md §11:
1. SSE streaming via libcurl FFI (existing WRITEFUNCTION hook)
2. PTY-backed exec via forkpty(3); replaces popen + retires the §7
sentinel exit-code workaround in favor of waitpid
3. Session persistence as append-only JSONL under
<config.history.dir>/sessions/<utc>.jsonl
4. Readline custom bindings (rl_bind_keyseq); Phase 1 reserves \C-n
as a no-op for Phase 3's Norris consumer
Module growth (no new file names beyond the §4-stubs):
ffi/curl -> M.post_sse(url, body, headers, on_event)
ffi/pty -> M.spawn / read / write / close / wait
ffi/libc -> waitpid + WEXITSTATUS + tcgetattr/tcsetattr
ffi/readline -> M.bind(seq, fn)
broker -> M.chat_stream; M.chat becomes a buffering wrapper
executor -> PTY path; sentinel hack deleted
repl -> :save, :resume <name>, :sessions; streaming render
renderer -> assistant_delta + assistant_flush
history -> open / append / load / list_sessions
Open questions Q11–Q16 (six new) tracked in §10:
- SSE shape uniformity across OpenRouter routes (Q11, Phase 7)
- CMD: highlight-on-stream strategy (Q12, plan phase)
- tty raw-mode recovery on Lua error (Q13, plan phase)
- bind \C-n now or defer to Phase 3 (Q14, plan phase)
- :resume into non-empty context (Q15, plan phase)
- session-log fsync policy (Q16, default close-only; tracked)
Next inner phase is "analyze": for each module change, identify
dependencies + risks + per-commit ordering. Then baseline (capture
Phase 0 behaviors we want to preserve), plan, review, implement, verify,
memory-update.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
marfrit
539408f480