blurt: Skill for Claude Code

Blurt guardrails

These are settled decisions. Don't reintroduce them; if a task seems to require one, stop and ask the user first. This is the fast "don't" list; AGENTS.md's "Settled decisions" table is the fuller reference and the source of truth.

Many of these are also enforced mechanically — scripts/check-invariants.sh (run by check.sh, including --portable) greps for the constructs that give each one away, so reintroducing one fails the health check rather than depending on this list being read. Those rules also pin a verbatim slice of the bullet they come from in this file, so rewording or deleting one fails the gate until someone decides whether the rule survives the edit — edit these entries knowing that, and fix the anchor in the same change. Treat that as a backstop, not the boundary: the rules it can't express are still here, still binding, and the reasons in this file are what let you tell an intended exception from a mistake. Never silence a finding with // invariant-ok: to get a build green — that marker is for a line that is genuinely correct, and reaching for it means it's time to stop and ask.

Audio

• No AVAudioEngine / installTap capture path. MicCapture builds a fresh AVCaptureSession recorder per capture (CaptureSessionRecorder; owner-directed move from AVAudioRecorder, 2026-08-25) — a long-lived engine bound its input graph to one device and went stale on a mic↔built-in switch (-10868, all-zero buffers), so no recorder survives across a device change. Keep the data output converting to 16 kHz mono 16-bit S16LE (the Sync API's geometry), published straight onto the feed start() returns with no resample pass. stop() answers a byte count, not the audio (owner-directed, 2026-09-08): the recording is uploaded in chunks as it is captured, and accumulating the blob as well copied every byte a second time inside the capture lock and held a duplicate of the whole utterance until release.
• One copy of the recording exists, for one reason. The transcriber keeps it (relay, AssemblyAITranscriber+LiveCapFallback.swift), on the upload's task and never in MicCapture's capture lock, solely to back the documented /v1/transcribe fallback when /v1/transcribe/live refuses a recording past its 120 s cap (413 with error_code: "audio_too_large"). That narrowed the 2026-09-08 "no retry-from-buffer path" rule on 2026-10-29; it did not open a general one. Don't read the copy back for a retry, a replay, a cache or any other second request, don't trigger the fallback on any other error, and don't move the copy into MicCapture. check-invariants.sh keeps the buffered route's path in that one file.
• (macOS shell) Don't pre-open the mic to make presses feel faster. MicCapture.warmUp() is stateless on purpose — build a session, drop it — and there is no warm or prepared recorder to reuse. Measured on hardware: building a session (or the retired prepareToRecord()) leaves the device closed and costs ~15 ms, while record()'s startRunning() opens it and costs 180–600 ms, so nothing can pre-pay the bring-up. A warm-recorder lifecycle was tried, and its device-identity check, pin check, 60 s expiry and bring-up flag all existed to protect ~15 ms. If you want the press to feel faster, the liveness gate's polling is where the remaining latency actually is.