docs(events): Phase 3 as built — the minimal admin surface #211

wtclaude · 2026-09-02T13:40:59Z

wtclaude commented

2026-09-02 13:40:59 +00:00

The docs half of Event System Phase 3. Pairs with RunicGateway/website #185.

Two files. EVENTS.md is 61 added / 4 deleted, and the four deletions are exactly the four lines that were genuinely rewritten (two API-table rows, the §L cancel row, and one sentence in §I). EVENTS_PLAN.md is 73 / 0 — purely additive.

`EVENTS.md`

§I — the GM cue now has both halves, and the "live controls that are honest" list gains a note saying six of its eight exist and two do not, for reasons rather than for scope: advance has no honest meaning until Phase 5 gives a phase an advance condition, and cancel's cleanup needs Phase 8's ledger.
§I also gains the reasoning for retry being one control, not two — retry is legal only from paused, and a paused run is paused at that step, so splitting them would read as honesty and behave as a trap — plus its two guards, and why attempts returning to zero is not Engagement Phase 14's rule being broken (that rule is about automatic sweeps; this is a named person deciding once).
§E — a run's status is re-read between steps, not only at the top of a tick. One tick drains up to EVENT_STEPS_PER_TICK steps from one run, so without this a pause pressed mid-batch is answered by dispatching another two dozen steps.
§L — the cancel row now says what happens to a parked step (cancelled with the pending ones: a cue is not a command already sent, it is an instruction nobody is holding), plus two new rows for the human skip and the human retry.
§ API surface — the control rows split so the table stops naming a route that does not exist; advance gets its own row marked not built; and the "what each phase built" note gains Phase 3's six routes, what is still absent and why, and the two derived response fields (waitingSteps on a run, parked on a step) with the reason they are derived rather than columns.

`EVENTS_PLAN.md`

Phase 3 marked complete, with the four org-lead decisions (2026-09-02, all as recommended) and the three things the build settled — including the two that are corrections:

A pause pressed mid-tick did nothing for up to 24 more steps. Found by writing the test; the test was re-run against the unfixed code to confirm it fails.
The retry guard was reading the wrong end of the phase — "the lowest seq that is not settled" looks equivalent to "the step the run is stopped at" and is not, because the runner steps over a failed step. Recorded because the wrong rule is the intuitive one.

Verify

docs has no CI. Every relative link and anchor in both files was checked by hand — all resolve. The working tree is CRLF under core.autocrlf=true, so both files were read universal-newline and written back \r\n; git diff --numstat is 61/4 and 73/0, and the deletions were compared against the real content diff to confirm none is a line-ending artefact.

AI-assisted: authored with Claude Code (Claude Opus).

The docs half of Event System **Phase 3**. Pairs with `RunicGateway/website` **#185**. Two files. `EVENTS.md` is **61 added / 4 deleted**, and the four deletions are exactly the four lines that were genuinely rewritten (two API-table rows, the §L cancel row, and one sentence in §I). `EVENTS_PLAN.md` is **73 / 0** — purely additive. ## `EVENTS.md` - **§I** — the GM cue now has both halves, and the "live controls that are honest" list gains a note saying **six of its eight exist and two do not, for reasons rather than for scope**: `advance` has no honest meaning until Phase 5 gives a phase an advance *condition*, and cancel's `cleanup` needs Phase 8's ledger. - **§I** also gains the reasoning for **retry being one control, not two** — retry is legal only from `paused`, and a paused run is paused *at* that step, so splitting them would read as honesty and behave as a trap — plus its two guards, and why `attempts` returning to zero is not Engagement Phase 14's rule being broken (that rule is about automatic *sweeps*; this is a named person deciding once). - **§E** — **a run's status is re-read between steps, not only at the top of a tick.** One tick drains up to `EVENT_STEPS_PER_TICK` steps from one run, so without this a pause pressed mid-batch is answered by dispatching another two dozen steps. - **§L** — the cancel row now says what happens to a **parked** step (cancelled with the pending ones: a cue is not a command already sent, it is an instruction nobody is holding), plus two new rows for the human skip and the human retry. - **§ API surface** — the control rows split so the table stops naming a route that does not exist; `advance` gets its own row marked **not built**; and the "what each phase built" note gains Phase 3's six routes, what is still absent and why, and the two **derived** response fields (`waitingSteps` on a run, `parked` on a step) with the reason they are derived rather than columns. ## `EVENTS_PLAN.md` Phase 3 marked complete, with the **four org-lead decisions** (2026-09-02, all as recommended) and the **three things the build settled** — including the two that are corrections: - **A pause pressed mid-tick did nothing for up to 24 more steps.** Found by writing the test; the test was re-run against the unfixed code to confirm it fails. - **The retry guard was reading the wrong end of the phase** — "the lowest seq that is not settled" looks equivalent to "the step the run is stopped at" and is not, because the runner steps *over* a failed step. Recorded because the wrong rule is the intuitive one. ## Verify `docs` has no CI. Every relative link and anchor in both files was checked by hand — all resolve. The working tree is CRLF under `core.autocrlf=true`, so both files were read universal-newline and written back `\r\n`; `git diff --numstat` is **61/4** and **73/0**, and the deletions were compared against the real content diff to confirm none is a line-ending artefact. --- - [x] AI-assisted: authored with Claude Code (Claude Opus).

wtclaude added 1 commit 2026-09-02 13:41:01 +00:00

docs(events): Phase 3 as built — the minimal admin surface 261cce6423

EVENTS.md: the six controls that exist and the two that do not, and why;
retry as one control with its two guards; what a cancel does to a parked cue;
the run status re-read between steps; the two derived response fields.

EVENTS_PLAN.md: Phase 3 complete, the four org-lead decisions, and the three
things the build settled — including the mid-batch pause defect and the retry
guard that was reading the wrong end of the phase.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T6t8mrAWhZU5vnyYgZTMtL

whitlocktech merged commit a8cc051f7a into edge

2026-09-02 15:47:15 +00:00

whitlocktech deleted branch docs/events-phase-3

2026-09-02 15:47:16 +00:00

whitlocktech referenced this issue from a commit

2026-09-02 15:47:18 +00:00

Merge pull request 'docs(events): Phase 3 as built — the minimal admin surface' (#211) from docs/events-phase-3 into edge

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#211