Decision packet: Spoken Edit count words ("delete the last twenty words")¶

Date / audited revision: 2026-11-06, main @ 8a72bbc6 Status: Proposal, not a decision. Nothing here changes code. The owner decides. Found: Round 7 review, deliberately left unfixed so it could be decided first. Related: ADR-v2-003 Spoken Edit Mode · ADR-021 invest in error cost · Mandarin count precedent src/yazses/commands/grammars/zh.py

Evidence labels: [Code] read in this checkout at 8a72bbc6 (file:line) · [Assumption] reasoning with no measurement · [Unknown] not established. No external source was used. No audio or transcript was used.

Coordination note. The unmerged branch r1107-commands (commit 3f4f0ea8, also carried by release/v2.50.0-rc2) already changes src/yazses/commands/edit_ops.py: it adds a _WORD regex (shifting every line after 15 down by one) and rewrites delete_last_words to slice the original text instead of re-joining words. It does not touch _NUMBER_WORDS, _n or _RE_DEL_WORDS. Line numbers below are at 8a72bbc6. Any implementation must start after that branch lands, or rebase onto it.

1. The defect, in one line¶

parse_edit("delete the last twenty words") returns ("delete_words", {"n": 1}). It deletes one word and reports success. Any count word the parser does not know becomes 1.

2. Current behaviour¶

2.1 The parser (pure module)¶

What the parser does with some inputs, read from the code above [Code]:

Digits rarely reach this parser. classify uses the Tier 1 grammar of one command language only (src/yazses/commands/grammar.py:77-90). With the English grammar, any digit count is caught first by en.py:58 (section 2.3), so the digit rows above reach parse_edit only when the command language is not English (for example zh, where an English phrase falls through to DICTATE). Word counts ("twenty", "few") always reach it.

2.2 Who reaches it (daemon)¶

• Command mode only. _try_spoken_edit is called at src/yazses/core/daemon.py:4799. That is inside the if command_mode: branch (daemon.py:4691). It runs only after classify(...) (daemon.py:4692-4695) returned DICTATE, meaning no grammar rule matched (daemon.py:4717). Ordinary prose dictation never reaches parse_edit [Code].
• Two opt-ins, both off by default. [commands] spoken_edit = False (src/yazses/config.py:520) gates the call (daemon.py:4796). [commands] spoken_edit_destructive = False (config.py:524) gates deletes. With it off, a delete is recognised, logged as spoken_edit_skipped and not applied (daemon.py:8030-8035) [Code].
• Bounded to the last dictation. The edit applies to self._ledger.last_text() (daemon.py:8036) through _replace_last_burst. The ledger stays updated, so "scratch that" undoes it (daemon.py:8010-8022). An over-count can at worst clear the last dictation. It cannot reach text from before that dictation [Code].

Who is affected today: users who turned on both flags and then say a count above ten or a non-number word. [Unknown] how many such users there are. Telemetry is forbidden, so this cannot be measured in the field.

2.3 The digit path is a different code path (adjacent finding)¶

The English grammar matches ^delete\s+(?:the\s+)?last\s+(\d+)\s+words?$ (src/yazses/commands/grammars/en.py:58) before Spoken Edit ever sees the phrase. The dispatcher then sends Ctrl+BackSpace n times (src/yazses/commands/dispatch.py:226-230). That path has no cap and no ledger bound. It is not gated by spoken_edit_destructive: "delete the last 500 words" sends 500 word-deletes into the focused app. The same holds for delete_lines (en.py:60) and undo_n (en.py:63, dispatch.py:241-244).

The Mandarin grammar already solved this. It uses a closed 0-99 count (zh.py:36-39, MAX_COUNT = 99) and a parser with "no fuzzy fallback" (zh.py:118-140, parse_command_number). Its destructive actions are reachable only through a literal prefix with a capped count (zh.py:285-290).

This packet is about the word path in edit_ops.py. The uncapped English digit path should be raised as its own issue so the two decisions stay separate. It is listed under "Owner decisions" below.

[Unknown] Which form Whisper or Parakeet produces for a spoken count ("20" or "twenty") has not been measured here. If the decoder mostly emits digits, most real traffic takes the grammar path in 2.3, not this one. That is why section 6 includes a measurement step.

3. Options¶

A. Extend the number vocabulary (closed set)¶

Recognise 0-99 as words: zero…nineteen, the tens twenty…ninety, and compounds twenty one / twenty-one. The set is closed and checked exactly. This is the same shape as zh.py.

• Fixes: "twenty", "eleven", "twenty one", "twenty-one".
• Does not fix on its own: "few", "bad" and "for". These still fall back to 1 unless B is also adopted.
• Cost: a pure helper (about 25 lines) plus a regex built from the vocabulary. Do not reuse itn/normalize.py:12-18 (_NUM). Its "oh": 0 belongs to version strings, and an import would couple two features that are both off by default.

B. Refuse an unknown count, with a notice¶

Delete the default=1 fallback. If the token is not in the vocabulary, return a recognised-but-refused result, for example ("edit_refused", {"reason": "unknown_count", "heard": "few"}). The daemon then shows one notice through its existing notification path (notify(...), as used at daemon.py:8000-8006):

Nothing deleted: "few" is not a number. Say, for example, "delete the last 3 words".

The daemon returns True, so nothing is typed and the event is filed as spoken_edit_refused.

• Fixes: every silent wrong count. A wrong action becomes no action plus one sentence.
• Order relative to the destructive gate: check the destructive gate first. With spoken_edit_destructive off, keep today's quiet spoken_edit_skipped. A notice about an operation the user never enabled would be noise.
• Rejected sub-option: mapping homophones ("for"→4, "to"/"too"→2, "won"→1). That is a heuristic guess, which is exactly what ADR-021 rules out (adr-021…md:85-87: "hold only on a specific, checkable signal, never on a heuristic"). Refusing and letting the user repeat costs one utterance. Deleting the wrong number of words costs a correction.

C. Cap the count¶

Accept counts only up to a ceiling, and refuse anything above it, by the same route as B.

• Spoken Edit path: this matters little here, because the ledger already bounds the harm (2.2), and with the English grammar a digit count never reaches this path (2.1). Its value is consistency, so that "delete the last 5000 words" gets the same refusal everywhere.
• Recommended ceiling: 99, the same as zh.py:39 (MAX_COUNT). One number across languages is easier to document and test.
• Grammar digit path (2.3): a cap there would change real behaviour, because nothing else bounds it. That is a separate decision.

D. Do nothing, but document it¶

Keep the fallback to 1 and document "counts up to ten". This is the cheapest option, but the failure stays silent: the user sees one word disappear and has no reason to believe the command was misunderstood.

4. Which phrases newly become commands¶

The key point: the frame regex already accepts any single token as the count (edit_ops.py:103-105). Options A and C on single tokens therefore create no new command phrases. They change only how many words a phrase that already matches will delete.

To keep A narrow, build the compound alternative from the vocabulary itself, as in (twenty|thirty|…|ninety)[\s-](https://github.com/MSKazemi/yazses/blob/main/design/research/one|…|nine). Do not widen the slot to \w+\s+\w+. A widened slot would also capture "delete the last bad french words" and send it down the refusal path, which adds notice traffic for no gain.

5. False-trigger risk (ADR-021: judged on how rarely it fires)¶

Two separate risks follow.

5.1 An unwanted destructive edit. Today's exposure is limited by three things already in the code [Code]:

1. the command key is held (daemon.py:4691);
2. no grammar rule matched (daemon.py:4717);
3. the user opted into both flags (config.py:520,524).

The harm is also bounded to the last dictation and undoable by "scratch that". A adds destructive reach only for compound counts, and only up to 99. A larger deletion than today, when the user really asked for twenty words, is the requested behaviour, not a false trigger. [Assumption] The residual risk is that the decoder turns "two" into "twenty". That is an ASR error which no parser can detect, and "scratch that" recovers it.

5.2 The refusal notice from B and C. ADR-021 asks how often the notice interrupts. It fires only when all of these hold:

• the command key is held;
• the utterance matches the exact frame delete [the] last <token> word(s);
• <token> is outside a closed, enumerable set (or above 99);
• spoken_edit_destructive is on.

The signal is specific and checkable: membership in a finite set, with no scoring or threshold. The release is free, because there is nothing to confirm: the user simply says the command again with a number. It never fires during prose dictation. [Assumption] It fires less often than any guard already shipped. That should be measured by the synthetic replay in 6.3 before it is claimed.

The notice is not a confirmation prompt. It holds nothing and asks nothing, so the "users learn to confirm reflexively" failure in ADR-021 (adr-021…md:89-92) does not apply.

6. Test plan (for whoever implements; none of this exists yet)¶

All tests are deterministic and offline, with no audio, model or microphone. Planned file: tests/test_spoken_edit_count_words.py.

6.1 Pure parser (edit_ops.py)¶

• Fails on 8a72bbc6: parse_edit("delete the last twenty words") == ("delete_words", {"n": 20}). Today it returns n=1.
• Exhaustive 0-99 round trip. For every n in 0..99, render the English words with an independent oracle written in the test: a small table-driven speller, not the production table. Then assert parse_edit(f"delete the last {words} words") gives n, in both the spaced and hyphenated compound forms. This follows the pattern of tests/test_mandarin_command_numerals.py, which proves regex and parser agree.
• Refusal (option B). few, several, couple, bad, for, hundred, twenty-ten and one hundred each give ("edit_refused", {"reason": "unknown_count", "heard": …}). None of them gives delete_words.
• Cap (option C). 100, 500 and 005 (zero-padded, as in zh.py:131-134) are refused. 99 is accepted.
• Unchanged. delete the last word gives n=1. delete the last passwords gives None. delete the last bad french words gives None (the slot was not widened). tests/test_edit_ops.py:67-70 still passes.
• apply_edit. A refused phrase returns EditResult(text, False) and is never dispatched as a delete. twenty on a 5-word burst clears it, which pins the ledger clamp.
• Optional property test. Use Hypothesis over delete the last <random token> words: the result is either n in 0..99 from the oracle, or a refusal. It is never n=1 for a token outside the vocabulary.

6.2 Daemon wiring (_try_spoken_edit, mocked ledger, injector and notify)¶

• spoken_edit_destructive=True with "delete the last few words": no injection, no _replace_last_burst call, notify called once, the event's intent_type is spoken_edit_refused, and the function returns True.
• spoken_edit_destructive=False with the same phrase: today's spoken_edit_skipped, and notify is not called.
• With "delete the last twenty words" and a 30-word ledger entry, the retyped text is the first 10 words.

6.3 Firing-rate check (ADR-021)¶

Use a synthetic list of command-mode utterances: the existing grammar fixtures, plus generated delete the last <n> words phrases, plus non-count fillers. Count how often the refusal fires, and assert it fires only on the frame. The list must be synthetic or explicitly de-identified (AGENTS.md: no real transcripts).

Decoder-output measurement ([Unknown] in 2.3). Synthesise TTS clips of "delete the last twenty words" and similar phrases, then record whether the pinned decoder emits digits or words. This decides whether the word path or the uncapped digit path carries real traffic.

6.4 Gates once implemented¶

uv run python -m pytest tests/test_spoken_edit_count_words.py tests/test_edit_ops.py \
  tests/test_spoken_edit_does_not_match_a_word_ending_in_words.py -v
uv run python -m pytest tests/ -n auto
uv run ruff check src tests scripts
uv run mypy src

There is no config key, CLI flag or generated-doc change, so scripts/gen-docs.py is not needed. A CHANGELOG entry is.

7. Recommendation (proposal)¶

Adopt A + B + C together, on the Spoken Edit word path only:

• a closed 0-99 vocabulary, with hyphenated or spaced compounds built from that vocabulary;
• no fallback; an unknown or over-cap count gives one notice and deletes nothing;
• the same ceiling as Mandarin (99).

This removes a silent wrong action. On single-token phrases it adds no new command phrases. Its only new interruption fires on a closed-set membership test, in command mode, behind two opt-ins.

Not recommended:

• homophone mapping, because it is a heuristic (ADR-021);
• widening the count slot to free text;
• reusing itn/_NUM.

8. Owner decisions¶

1. Accept A + B + C for edit_ops.py, or pick a subset. D, documenting "up to ten", is the minimum honest option.
2. Wording of the refusal notice, and whether it also appears on the overlay or only as a desktop notification.
3. Separate issue: cap the English grammar digit path (en.py:58,60,63 and dispatch.py:226-244) at 99, as Mandarin does. Today "delete the last 500 words" sends 500 Ctrl+BackSpace presses with no opt-in beyond the command key.
4. Whether ADR-v2-003 needs a note. Its point 3 (adr-v2-003…md:24-25) promises a confirm step for multi-word deletes. The code instead uses an opt-in flag plus "scratch that" (daemon.py:8014-8018). That gap predates this packet and is out of scope, but whoever revisits the ADR should know about it.