Skip to content

Move alert mechanism to the code it constrains; compress alert.md - #718

Merged
nedtwigg merged 4 commits into
alert-drop-ringseqfrom
alert-spec-compress
Sep 21, 2026
Merged

nedtwigg merged 4 commits into
alert-drop-ringseqfrom
alert-spec-compress

Conversation

@nedtwigg

Copy link
Copy Markdown
Member

Stacked on #717. Docs plus code comments; no behavior change.

AGENTS.md → Specs: mechanism that constrains one module lives as a comment at that code, the spec keeps the one-line rule and a Source of truth: pointer. alert.md violated that in several places. This PR moves:

  • the OSC 99 key grammar and the OSC 777 field rule → lib/src/lib/terminal-protocol.ts (the OSC 9;4 table stays; it is cross-module behavior);
  • the speech-queue bounds (64 pending, 60 s engine timeout, callback-identity revocation, no retry) → lib/src/lib/speech-queue.ts;
  • the push-device-list refresh fencing → lib/src/remote/burrow/alert-push.ts (mostly already there);
  • two why-clauses → the rationale; the Await section trimmed 911 → 808 words with every bullet kept.

A second reviewer pass restored three conditions the first cut had dropped (the grace window resolves idle unless cancelled; delivery resumes only when adopt_done succeeds; transport.md carries the relay messages, not the alert:await contract). Front matter now names what the spec defers and to whom.

alert.md budget 7050 → 6750. Every Source of truth: symbol verified by spec-lint check 12.

🤖 Generated with Claude Code

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Sep 20, 2026

Copy link
Copy Markdown

Deploying mouseterm with  Cloudflare Pages  Cloudflare Pages

Latest commit: 58f1180
Status: ✅  Deploy successful!
Preview URL: https://31ba232f.mouseterm.pages.dev
Branch Preview URL: https://alert-spec-compress.mouseterm.pages.dev

View logs

@dormouse-bot dormouse-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Feedback on work in progress, not a merge verdict — mark ready when you want the full review.

The speech-queue bullet keeps the pointer but drops the rule. AGENTS.md → Specs: mechanism constraining a single module lives as a comment at that code, "the spec keeping the one-line rule and a Source of truth: pointer". alert.md now carries only "Queue bounds, the engine timeout, and callback-identity revocation live at SpeechQueue." — no rule survives that sentence, so nothing above the fold says the queue is bounded at all. Compare what this PR did with OSC 777/99, where a bolded one-line rule stayed and only the grammar moved. The numbers (64, 60 s) are the module's mechanism and belong in the TSDoc where you put them; "bound the queue, cancel a stalled attempt, never retry" is the rule.

The ratchet has no room for it. alert.md is at 6,749 words against the new 6,750, so the suggestion below lands at 6,768 and needs node scripts/spec-lint.mjs --ratchet docs/specs/alert.md in the same PR — budget 6,750 → 6,800, still well under the 7,050 it started at.

Comment thread docs/specs/alert.md Outdated
@nedtwigg
nedtwigg added this pull request to stack #722 September 21, 2026 04:33
@nedtwigg
nedtwigg marked this pull request as ready for review September 21, 2026 05:27
nedtwigg and others added 4 commits September 20, 2026 22:37
The OSC 777/99 grammars, the speech queue's bounds and timeout, and the
push device-list fencing each constrain one module, so they now live as
comments there while alert.md keeps the one-line rule and its
`Source of truth:` pointer. Await, Live Workspace transfer, and Alarm
settings lose repeated framing and a tour of stores they do not own;
transaction order defers to standalone.md, which states it. Front matter
now names what the spec defers, and the retired bell no longer rings in
the Await absorption rule.

No behavior change.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The await grace window resolves idle unless output or a command start
cancels it; delivery on a transferred Workspace resumes only when
adopt_done succeeds; and transport.md carries the alert-store relay
messages, not the alert:await contract, which stays here.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@nedtwigg
nedtwigg merged commit 77a0851 into main Sep 21, 2026
25 of 26 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants