Add undo, back, and flip commands; harden click-mid-readout switching

Three new voice commands (REQ-ANS-017, REQ-NAV-009, REQ-NAV-010):

- undo (also heard as "undue"): reverts the last answer the session
  entered — cells that were empty before are cleared, letters the entry
  overwrote are restored — then re-selects that clue and prompts "say the
  answer again, or say spell it". One level deep; with nothing to revert
  it says so. In spelling mode "undo" keeps meaning remove-a-letter.
- back: previous clue in list order, wrapping from the first Across to
  the last Down. Filled entries are NOT skipped — back exists to revisit
  and fix what's already there.
- flip: jumps to the crossing clue (the perpendicular entry at the
  current clue's first crossed cell) — across ⇄ down.

Plumbing: new UNDO machine action executed via clearEntry + enterAnswer
with the watcher paused, new UNDO_RESULT event, and lastEntry bookkeeping
captured at ENTER time so undo restores the exact pre-entry pattern.

Click-mid-readout fix-up (REQ-NAV-008): following a click is now scoped
to moments that end in listening. While an accepted answer is being
confirmed and written (between "Fits!" and the letters landing), a click
no longer cancels the flow — previously it silently discarded the
accepted word. An end-to-end orchestrator test now pins the full
click-during-readout behavior: speech cut immediately, clicked clue read
next.

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

Author: claude

docs/ARCHITECTURE.md

@@ -96,10 +96,12 @@ DOM numbers (REQ-MODEL-001) — the page adapter stays dumb.
 
 ### Machine events (into `machine.reduce`)
 `START{snapshot}` · `TTS_DONE` · `HEARD{alternatives:[{transcript,confidence}]}` · `BARGE_IN` ·
-`STT_ERROR{code}` · `ENTRY_RESULT{ok,snapshot}` · `PAGE_EVENT{kind,snapshot}` · `TOGGLE_OFF`
+`STT_ERROR{code}` · `ENTRY_RESULT{ok,snapshot}` · `UNDO_RESULT{ok,snapshot}` ·
+`PAGE_EVENT{kind,snapshot}` · `TOGGLE_OFF`
 
 ### Machine actions (out of `machine.reduce`)
-`SAY{say:{kind,...}}` · `LISTEN` · `ENTER{clueId,word}` · `SELECT_CLUE{clueId}` · `END`
+`SAY{say:{kind,...}}` · `LISTEN` · `ENTER{clueId,word}` · `UNDO{clueId,cells}` ·
+`SELECT_CLUE{clueId}` · `END`
 
 The machine is a **pure reducer**: same state + event → same actions, every time. That makes the
 entire dialog policy (the trickiest behavior in the product) unit-testable as data — every
@@ -119,6 +121,8 @@ dispatch(event):
                    intent cancels the utterance and dispatches BARGE_IN — REQ-CMD-006)
     LISTEN      → stt.listenOnce() → dispatch(HEARD | STT_ERROR)
     ENTER       → pause watcher → pageClient.enterAnswer(...) → dispatch(ENTRY_RESULT)
+    UNDO        → pause watcher → clearEntry(blank-before cells) + enterAnswer(overwritten
+                   letters) → dispatch(UNDO_RESULT) — reverts the last entry (REQ-ANS-017)
     SELECT_CLUE → pageClient.selectClue(...)
     END         → teardown (cancel tts/stt, stop watcher, disconnect port)
 ```

docs/MANUAL-TESTS.md

@@ -190,3 +190,12 @@ Covers: REQ-CMD-006
 2. Start again; mid-readout say something that is NOT a stop word (e.g. "hello there").
 3. **PASS:** step 1 — the readout halts promptly and you get the short sign-off, session over.
    Step 2 — the readout continues unaffected and your words are not treated as an answer.
+
+### MT-26 — Undo, back, flip
+Covers: REQ-ANS-017 REQ-NAV-009 REQ-NAV-010
+1. Enter a fitting answer by voice; after the session moves on, say "undo".
+2. Say "back". Then say "flip".
+3. **PASS:** undo re-selects the answered clue, empties exactly the cells that answer filled
+   (letters that were there beforehand come back), and prompts you to say it again or spell it;
+   "back" moves to the previous clue in the list — including filled ones — and reads it; "flip"
+   jumps to the crossing clue and reads it; the page highlight follows every move.

docs/REQUIREMENTS.md

@@ -399,12 +399,36 @@ entities. The readout must convey what the eye would see.
 - If the user clicks a different clue/cell on the page during the session, the conversation MUST
   follow it immediately: abandon whatever it was doing (an in-flight readout is cut short;
   spelling/disambiguation/confirmation modes reset) and read the newly selected clue. Selection
-  changes caused by our own writing/navigation MUST NOT trigger this (no echo loops).
+  changes caused by our own writing/navigation MUST NOT trigger this (no echo loops). One
+  exception: while an accepted answer is being confirmed and written (between "Fits!" and the
+  letters landing), the click is NOT followed — following would silently discard the answer.
 - **Accept:** Given a session on 1A — listening, mid-readout, or in a sub-mode — when the page
   selection changes to 3D (user click), then 3D is read; when selection events arrive for the clue
   we already track, nothing happens.
 - **Verify:** unit `tests/unit/machine.test.js`; manual MT-13.
 
+#### REQ-NAV-009 — "back" goes to the previous clue
+- **Status:** Active · **Level:** MUST
+- *back* / *go back* / *previous* MUST move to the previous clue in list order — wrapping from the
+  first Across to the last Down — read it, and sync the page highlight. Unlike *next*
+  (REQ-NAV-003), filled entries are NOT skipped: going back exists to revisit and fix what is
+  already there. The active strategy does not affect *back* (list order always — "previous" under
+  most-filled has no stable meaning).
+- **Accept:** Given the current clue is 6 Across with 1 Across filled, when the user says "back",
+  then 1 Across is selected and read; given the current clue is the first Across, then "back"
+  lands on the last Down.
+- **Verify:** unit `tests/unit/machine.test.js`; manual MT-26.
+
+#### REQ-NAV-010 — "flip" switches to the crossing clue
+- **Status:** Active · **Level:** MUST
+- *flip* MUST switch from the current clue to the perpendicular clue that crosses it (the crossing
+  at the entry's first crossed cell, REQ-MODEL-002), read it, and sync the page highlight. Flipping
+  again returns to a clue in the original direction. When the entry has no crossing at all, say so
+  briefly and keep listening.
+- **Accept:** Given the current clue is 1 Across, when the user says "flip", then 1 Down (the
+  crossing at its first cell) is selected and read.
+- **Verify:** unit `tests/unit/machine.test.js`; manual MT-26.
+
 ---
 
 ## 8. Answers: hearing, checking, entering (ANS)
@@ -594,6 +618,21 @@ This is the heart of the product. Speech recognition is *phonetic*; crossword an
   "yes" rewrites the entry.
 - **Verify:** unit `tests/unit/machine.test.js`.
 
+#### REQ-ANS-017 — Undo the last entered answer
+- **Status:** Active · **Level:** MUST
+- *undo* (STT often hears it as "undue" — both MUST work) MUST revert the most recent answer the
+  session entered: every cell of that entry returns to what it held just before the entry —
+  previously empty cells are cleared, overwritten letters are restored. The conversation MUST move
+  back to that clue (page highlight synced) and prompt the user to say the answer again or spell
+  it. With no entry to revert (none made yet, or right after an undo), reply that there is nothing
+  to undo. Undo history is one level deep — a second consecutive *undo* does not go further back.
+  In spelling mode, *undo* keeps its spelling meaning (remove the last letter, REQ-ANS-011).
+- **Accept:** Given HEART was entered into an empty 1 Across and the session moved on, when the
+  user says "undo", then the five cells are empty again, 1 Across is selected, and the prompt asks
+  to say it again or spell it; a repeated "undo" reports nothing to undo. Given HEIST was entered
+  over crossing letters via *anyway*, then "undo" restores those letters.
+- **Verify:** unit `tests/unit/machine.test.js`, `tests/unit/matching.test.js`; manual MT-26.
+
 ---
 
 ## 9. Hints (HINT)
@@ -630,6 +669,9 @@ This is the heart of the product. Speech recognition is *phonetic*; crossword an
 | Intent | Utterances |
 |---|---|
 | next | next · next clue · next one · pass · pass on this · skip · skip it · skip this one · move on |
+| back | back · go back · previous · previous clue · previous one |
+| flip | flip · flip it · switch direction · change direction · other direction |
+| undo | undo · undue · undo that · undo it · take that back · take it back |
 | repeat | repeat · repeat that · again · say again · say that again · read it again · what · come again |
 | hint | hint · hints · give me a hint · what do i have · what's there · what's filled in · read the letters · pattern |
 | help | help · what can i say · commands · options |
@@ -653,8 +695,8 @@ This is the heart of the product. Speech recognition is *phonetic*; crossword an
 
 #### REQ-CMD-002 — Help
 - **Status:** Active · **Level:** MUST
-- *help* MUST speak a one-breath summary of the core commands (answer, pass/next, repeat, hint,
-  spell, stop) and keep listening.
+- *help* MUST speak a one-breath summary of the core commands (answer, pass/next, back, flip,
+  repeat, hint, spell, undo, stop) and keep listening.
 - **Accept:** Given "help", then the help utterance is spoken and the clue stays current.
 - **Verify:** unit `tests/unit/machine.test.js`; manual MT-16.
 

extension/src/app/orchestrator.js

@@ -10,7 +10,8 @@ import { parseCommand } from '../matching/commands.js';
  * @param {{speak(text):Promise, cancel():void}} deps.tts
  * @param {{listenOnce():Promise, stop():void}} deps.stt
  * @param {object} deps.pageClient
- *   {snapshot, enterAnswer(cells), selectClue(clueId), watch(cb), unwatch, pauseWatch, resumeWatch}
+ *   {snapshot, enterAnswer(cells), clearEntry(cellIndices), selectClue(clueId),
+ *    watch(cb), unwatch, pauseWatch, resumeWatch}
  * @param {object} [deps.ui]  {caption(role, text), listening(bool)}
  * @param {() => void} [deps.onEnd]
  * @param {() => number} [deps.now]  clock, injectable for tests
@@ -96,6 +97,28 @@ export function createOrchestrator({ tts, stt, pageClient, ui = {}, onEnd = () =
         }
         break;
       }
+      case 'UNDO': {
+        // Revert the last entry (REQ-ANS-017): null letters mean "clear the cell",
+        // real letters mean "restore what our entry overwrote".
+        try {
+          pageClient.pauseWatch?.();
+          const clears = action.cells.filter((c) => !c.letter).map((c) => c.index);
+          const restores = action.cells.filter((c) => c.letter);
+          let ok = true;
+          let snap = null;
+          if (clears.length) ({ ok, snapshot: snap } = await pageClient.clearEntry(clears));
+          if (restores.length) {
+            const res = await pageClient.enterAnswer(restores);
+            ok = ok && res.ok;
+            snap = res.snapshot;
+          }
+          pageClient.resumeWatch?.();
+          enqueue({ type: 'UNDO_RESULT', ok, snapshot: snap ?? await pageClient.snapshot() });
+        } catch {
+          pageLost();
+        }
+        break;
+      }
       case 'SELECT_CLUE': {
         try {
           await pageClient.selectClue(action.clueId);
@@ -142,9 +165,12 @@ export function createOrchestrator({ tts, stt, pageClient, ui = {}, onEnd = () =
       if (event.kind === 'solved' || event.kind === 'selection') stt.stop();
       if (event.kind === 'selection') {
         // REQ-NAV-008: clicking another clue takes effect NOW — cut any readout short.
-        // Our own SELECT_CLUE echoes back with the clue we already track, so it never cancels.
+        // Our own SELECT_CLUE echoes back with the clue we already track, so it never
+        // cancels; neither does a click the machine won't follow (entry in flight).
         const sel = event.snapshot?.selection?.clueId;
-        if (sel && sel !== state.clueId) tts.cancel();
+        const willFollow = state.phase === 'listening'
+          || (state.phase === 'speaking' && state.after === 'listen');
+        if (sel && sel !== state.clueId && willFollow) tts.cancel();
       }
     }
     queue.push(event);

extension/src/conversation/machine.js

@@ -1,15 +1,16 @@
 // Conversation policy: pure reducer (state, event) → {state, actions}.
 // No browser APIs, no English strings (see phrases.js), no DOM (see page-adapter).
 //
-// Events in:  START TTS_DONE HEARD BARGE_IN STT_ERROR ENTRY_RESULT PAGE_EVENT TOGGLE_OFF
-// Actions out: SAY LISTEN ENTER SELECT_CLUE END
+// Events in:  START TTS_DONE HEARD BARGE_IN STT_ERROR ENTRY_RESULT UNDO_RESULT
+//             PAGE_EVENT TOGGLE_OFF
+// Actions out: SAY LISTEN ENTER UNDO SELECT_CLUE END
 //
 // Half-duplex invariant (REQ-SPCH-005): LISTEN is never emitted in the same action
 // batch as SAY; listening starts only after speech finishes (TTS_DONE → after:'listen').
 // The shell's stop-only barge-in listener (REQ-CMD-006) surfaces here as BARGE_IN.
 
 import { buildModel } from '../puzzle-model/model.js';
-import { nextClue } from './strategies.js';
+import { nextClue, prevClue } from './strategies.js';
 import { evaluate, collectSpelledLetters } from '../matching/evaluate.js';
 import { parseCommand } from '../matching/commands.js';
 
@@ -48,22 +49,37 @@ function readClue(state, extra = {}, leadActions = []) {
   return speak(state, [...leadActions, say(clueSay(state.model, state.clueId, extra))], 'listen');
 }
 
-function advance(state, leadSays = []) {
-  const next = nextClue(state.model, state.clueId, state.strategy);
-  if (!next) {
-    // Nothing unfilled anywhere (REQ-LIFE-006 / REQ-NAV-003).
-    return listenAgain(state, [...leadSays, { kind: 'grid-full-wrong' }]);
-  }
-  const s = {
+/** Land on a clue with a clean slate: sub-mode, buffers, and pending work all reset. */
+function moveTo(state, clueId) {
+  return {
     ...state,
-    clueId: next.clueId,
+    clueId,
     mode: 'normal',
     rejected: [],
     lastProposed: null,
     pendingWord: null,
+    pendingEntry: null,
     spellBuffer: [],
     disambigWords: [],
   };
+}
+
+/** Navigate to a clue, sync the page, and read it (back/flip — REQ-NAV-009/010). */
+function goTo(state, clueId) {
+  const s = moveTo(state, clueId);
+  return speak(s, [
+    { type: 'SELECT_CLUE', clueId },
+    say(clueSay(s.model, clueId)),
+  ], 'listen');
+}
+
+function advance(state, leadSays = []) {
+  const next = nextClue(state.model, state.clueId, state.strategy);
+  if (!next) {
+    // Nothing unfilled anywhere (REQ-LIFE-006 / REQ-NAV-003).
+    return listenAgain(state, [...leadSays, { kind: 'grid-full-wrong' }]);
+  }
+  const s = moveTo(state, next.clueId);
   return speak(s, [
     ...leadSays.map(say),
     { type: 'SELECT_CLUE', clueId: next.clueId },
@@ -131,6 +147,30 @@ function handleCommand(state, cmd) {
   switch (cmd.command) {
     case 'next':
       return advance(state);
+    case 'back': // REQ-NAV-009: previous in list order, filled entries included
+      return goTo(state, prevClue(state.model, state.clueId).clueId);
+    case 'flip': { // REQ-NAV-010: jump to the crossing clue
+      const clue = state.model.clue(state.clueId);
+      let cross = null;
+      for (let i = 0; i < clue.cellIndices.length && !cross; i++) {
+        cross = state.model.crossingAt(state.clueId, i);
+      }
+      if (!cross) return listenAgain(state, [{ kind: 'no-crossing' }]);
+      return goTo(state, cross.clueId);
+    }
+    case 'undo': { // REQ-ANS-017: revert the last entry we made
+      if (!state.lastEntry) return listenAgain(state, [{ kind: 'nothing-to-undo' }]);
+      const { clueId, before } = state.lastEntry;
+      const cells = state.model.clue(clueId).cellIndices
+        .map((index, i) => ({ index, letter: before[i] })); // letter null → clear the cell
+      return {
+        state: { ...moveTo(state, clueId), phase: 'undoing', lastEntry: null },
+        actions: [
+          { type: 'SELECT_CLUE', clueId },
+          { type: 'UNDO', clueId, cells },
+        ],
+      };
+    }
     case 'repeat':
       return readClue({ ...state, mode: 'normal' }); // REQ-READ-009
     case 'hint': {
@@ -307,6 +347,7 @@ function onStart(state, { snapshot }) {
     disambigWords: [],
     pendingWord: null,
     pendingEntry: null,
+    lastEntry: null,
     rejected: [],
     lastProposed: null,
     sttRetried: false,
@@ -325,7 +366,13 @@ function onTtsDone(state) {
   if (state.after === 'enter') {
     const word = state.pendingEntry.word;
     return {
-      state: { ...state, phase: 'entering' },
+      // Remember what the entry held BEFORE this write, so "undo" can revert it
+      // exactly — clearing what we added, restoring what we overwrote (REQ-ANS-017).
+      state: {
+        ...state,
+        phase: 'entering',
+        lastEntry: { clueId: state.clueId, before: state.model.patternFor(state.clueId) },
+      },
       actions: [{
         type: 'ENTER',
         clueId: state.clueId,
@@ -380,33 +427,32 @@ function onPageEvent(state, { kind, snapshot }) {
     );
   }
   // REQ-NAV-008: a click reaches us while listening AND mid-readout (the shell cuts the
-  // audio short); only 'entering' and the farewell (after:'end') are off-limits.
+  // audio short). Off-limits: entering, the farewell, and the beat between an accepted
+  // answer and its letters landing (after:'enter') — following there would silently
+  // discard the answer.
   const interactive = state.phase === 'listening'
-    || (state.phase === 'speaking' && state.after !== 'end');
+    || (state.phase === 'speaking' && state.after === 'listen');
   if (!interactive) return { state, actions: [] };
   const model = buildModel(snapshot);
   if (kind === 'selection') {
     const sel = snapshot.selection?.clueId;
     if (sel && sel !== state.clueId && model.clue(sel)) {
       // The click wins over whatever was in progress: reset any sub-mode and pending work.
-      return readClue({
-        ...state,
-        model,
-        clueId: sel,
-        mode: 'normal',
-        rejected: [],
-        lastProposed: null,
-        pendingWord: null,
-        pendingEntry: null,
-        spellBuffer: [],
-        disambigWords: [],
-      });
+      return readClue({ ...moveTo(state, sel), model });
     }
   }
   // grid change (user typed manually) or same-clue selection: absorb the fresh state.
   return { state: { ...state, model }, actions: [] };
 }
 
+// REQ-ANS-017: the page finished reverting our last entry.
+function onUndoResult(state, { ok, snapshot }) {
+  if (state.phase !== 'undoing') return { state, actions: [] };
+  const s = { ...state, model: buildModel(snapshot) };
+  if (!ok) return listenAgain(s, [{ kind: 'entry-failed' }]);
+  return listenAgain(s, [{ kind: 'undone' }]); // prompt: say it again, or spell it
+}
+
 // REQ-CMD-006: "stop" heard by the barge-in listener while we were speaking.
 function onBargeIn(state) {
   if (state.phase !== 'speaking') return { state, actions: [] };
@@ -436,6 +482,7 @@ export function reduce(state, event) {
     case 'BARGE_IN': return onBargeIn(state);
     case 'STT_ERROR': return onSttError(state, event);
     case 'ENTRY_RESULT': return onEntryResult(state, event);
+    case 'UNDO_RESULT': return onUndoResult(state, event);
     case 'PAGE_EVENT': return onPageEvent(state, event);
     case 'TOGGLE_OFF': // REQ-LIFE-002: instant, silent teardown
       return { state: { ...state, phase: 'done' }, actions: [{ type: 'END' }] };

extension/src/conversation/phrases.js

@@ -130,7 +130,7 @@ export function render(say) {
       return `${letters}. ${summary}`;
     }
     case 'help':
-      return 'You can: say an answer, or answer followed by a word. Say pass or next to skip, repeat to hear the clue again, hint for the letters so far, spell it to spell, anyway to enter over a clash, switch to most filled to change order, or goodbye to stop.';
+      return 'You can: say an answer, or answer followed by a word. Say pass or next to skip, back for the previous clue, flip for the crossing clue, repeat to hear the clue again, hint for the letters so far, spell it to spell, undo to take back the last answer, anyway to enter over a clash, switch to most filled to change order, or goodbye to stop.';
     case 'didnt-catch':
       return "Sorry, I didn't catch that. Say an answer, or say help.";
     case 'misheard-reprompt':
@@ -141,6 +141,12 @@ export function render(say) {
       return say.letters.length ? `${say.letters.join(', ')}.` : 'Nothing yet.';
     case 'spell-cancelled':
       return 'Okay, back to normal answers.';
+    case 'undone':
+      return 'Undone — those letters are out. Say the answer again, or say spell it.';
+    case 'nothing-to-undo':
+      return "There's nothing to undo yet.";
+    case 'no-crossing':
+      return 'No crossing clue there.';
     case 'strategy-ack':
       return say.strategy === 'most-filled' ? 'Okay — most filled first.' : 'Okay — in list order.';
     case 'goodbye':

extension/src/conversation/strategies.js

@@ -36,3 +36,16 @@ export function nextClue(model, fromId, strategy = 'list-order') {
   }
   return null;
 }
+
+/**
+ * Previous clue in list order, wrapping from the first Across to the last Down
+ * (REQ-NAV-009). Unlike nextClue, filled entries are NOT skipped — "back" exists
+ * to revisit and fix what is already there. Always list order, whatever the
+ * active strategy: "previous" has no stable meaning under most-filled.
+ * @returns {{clueId: string}}
+ */
+export function prevClue(model, fromId) {
+  const order = model.orderedClueIds;
+  const start = Math.max(order.indexOf(fromId), 0);
+  return { clueId: order[(start - 1 + order.length) % order.length] };
+}