@@ -51,6 +51,22 @@ Bootstrapped 2026-08-02 from the first archived feature (Gemini Model Support).
5151- ** US2 (P1) — Disable launch at login.** A user unchecks the box; the app
5252 deregisters as a login item and no longer starts automatically.
5353
54+ ### Reliable Selection Reading (Dormant Accessibility Trees) ` [Source: specs/005-teams-ax-recovery/spec.md] `
55+
56+ - ** US1 (P1) — Fix text in an app whose accessibility tree is dormant.** After
57+ Microsoft Teams restarts (or updates, or the Mac reboots), a user selects text
58+ and invokes an action. Instead of failing instantly with "Cannot find the
59+ focused text element" until an external assistive tool touches the app,
60+ Overtype detects the dormant tree, wakes it, retries briefly, and completes
61+ the transformation.
62+ - ** US2 (P2) — No regression for well-behaved apps.** In apps whose accessibility
63+ support works immediately (native apps, Outlook, warmed-up Teams), latency and
64+ behavior are unchanged and no wake-up flags are set on the target application.
65+ - ** US3 (P3) — Failures still fail fast and clearly.** With nothing selected, or
66+ in a genuinely unsupported app, the run ends with the same specific error as
67+ before, after a bounded retry window; Escape during that window cancels
68+ immediately.
69+
5470### GUI Configuration Settings ` [Source: specs/003-gui-settings] `
5571
5672- ** US1 (P1) — Manage AI providers and credentials.** A user adds/edits/deletes
@@ -122,10 +138,17 @@ original 001 identifier is shown in parentheses.
122138 ongoing tasks that does not steal keyboard focus.
123139- ** FR-021** (orig FR-008): The system MUST sanitize AI responses to strip
124140 markdown and unnecessary quotes when appropriate.
125- - ** FR-022** (orig FR-009): The system MUST allow users to cancel in-flight AI
126- requests seamlessly (e.g., Escape).
141+ - ** FR-022** (orig FR-009): The system MUST allow users to cancel in-flight runs
142+ seamlessly (e.g., Escape). This includes cancellation during the dormant-tree
143+ recovery window (FR-035), which MUST end the run promptly with no modification
144+ to the target document.
145+ ` [Source: specs/001-overtype/spec.md -> FR-009; specs/005-teams-ax-recovery/spec.md -> FR-006] `
127146- ** FR-023** (orig FR-010): The system MUST NOT silently fail; all errors MUST be
128- presented to the user clearly.
147+ presented to the user clearly. Exhausting the dormant-tree recovery window
148+ (FR-035) MUST end the run with the same specific, typed errors as a
149+ single-shot lookup failure — no new silent failure modes and no indefinite
150+ waiting.
151+ ` [Source: specs/001-overtype/spec.md -> FR-010; specs/005-teams-ax-recovery/spec.md -> FR-007] `
129152
130153#### Launch at Login ` [Source: specs/002-launch-at-login] `
131154
@@ -169,6 +192,37 @@ parentheses.
169192 (speed multiplier, chunk size, delay, HUD visibility) and per-application
170193 overrides (add/remove bundle ids with custom delay/chunk size).
171194
195+ #### Reliable Selection Reading (Dormant Accessibility Trees) ` [Source: specs/005-teams-ax-recovery/spec.md] `
196+
197+ IDs renumbered on archival to avoid collision; original 005 identifier in
198+ parentheses. Cancellation (orig FR-006) and the unchanged error surface (orig
199+ FR-007) were consolidated into FR-022 and FR-023 rather than restated here.
200+
201+ - ** FR-035** (orig FR-001): When the existing focused-element lookup strategies
202+ find no element with a live selection, the system MUST attempt a bounded
203+ recovery instead of failing immediately.
204+ - ** FR-036** (orig FR-002): The recovery MUST wake the target application's
205+ accessibility support by setting the two known assistive-client flags on the
206+ target application, and MUST ignore the reported result codes of those calls,
207+ because at least one target application (Microsoft Teams) reports an error
208+ while honoring the call. This site MUST carry an inline comment naming the
209+ quirk (Principle III).
210+ - ** FR-037** (orig FR-003): The recovery MUST retry the focused-element lookup,
211+ querying the application element first, up to 24 attempts at 150 ms intervals.
212+ Ordering and interval come from the 2026-07-31 axprobe findings (binding
213+ conclusion #3 ); the attempt count was raised from that report's 12 after the
214+ 2026-08-02 acceptance run showed a truly cold Teams populates the selection
215+ attribute only about 2.7 seconds after the wake.
216+ - ** FR-038** (orig FR-004): The recovery MUST apply a bounded messaging timeout
217+ (2 seconds) to accessibility queries issued during the recovery, so a hung
218+ target application cannot stall a run beyond the hard timeout.
219+ - ** FR-039** (orig FR-005): The fast path MUST remain unchanged: if the existing
220+ strategies find the selection, no flags are set, no retries occur, and no
221+ latency is added.
222+ - ** FR-040** (orig FR-008): The empirical basis and the per-application outcome
223+ MUST be recorded in ` docs/compatibility.md ` (Teams dormant-tree behavior, the
224+ wake-up quirk, and the re-verified acceptance results).
225+
172226### Key Entities
173227
174228#### Gemini Model Support ` [Source: specs/004-gemini-provider] `
@@ -196,6 +250,18 @@ No new entities — the GUI edits the existing base entities. Concrete
196250` ProviderConfig ` (= Provider Configuration), ` ActionConfig ` (= Action
197251Configuration), and the Keychain Secret bound to a ` ProviderConfig.keychainKey ` .
198252
253+ #### Reliable Selection Reading (Dormant Accessibility Trees) ` [Source: specs/005-teams-ax-recovery/spec.md] `
254+
255+ No persistent entities, configuration schema, or stored state. Two runtime-only
256+ concepts, both function-local to the selection read:
257+
258+ - ** Recovery attempt** : a bounded sequence (wake flags once, then up to 24
259+ lookup retries at 150 ms) executed at most once per run.
260+ - ** Wake-up flags** : the two assistive-client attributes that signal "an
261+ assistive client is present" to the target application —
262+ ` AXEnhancedUserInterface ` (honored by Teams-like apps despite the reported
263+ error) and ` AXManualAccessibility ` (honored by Electron apps).
264+
199265### Edge Cases and Error Handling
200266
201267#### Gemini Model Support ` [Source: specs/004-gemini-provider] `
@@ -210,10 +276,16 @@ Configuration), and the Keychain Secret bound to a `ProviderConfig.keychainKey`.
210276
211277#### Overtype Foundation ` [Source: specs/001-overtype] `
212278
213- - Target app loses focus while a request is in flight → the write is aborted to
214- avoid replacing text in the wrong window.
279+ - Target app loses focus, or quits, while a request is in flight → the write is
280+ aborted to avoid replacing text in the wrong window. This holds equally when
281+ the app quits or loses frontmost status during the dormant-tree recovery
282+ window; the existing pre-write context re-check still applies.
283+ ` [Source: specs/001-overtype/spec.md; specs/005-teams-ax-recovery/spec.md] `
215284- Selecting text in an unsupported app (e.g., terminal emulator) → a clear
216- "unsupported" error, not a silent failure.
285+ "unsupported" error, not a silent failure. An app that never exposes a
286+ selection ends the bounded retry window in that same specific error; it is not
287+ retried indefinitely.
288+ ` [Source: specs/001-overtype/spec.md; specs/005-teams-ax-recovery/spec.md] `
217289- User is physically holding modifier keys when replacement starts → the app
218290 waits for physical modifier release before typing.
219291- AI wraps output in quotation marks the original lacked → the response sanitizer
@@ -237,6 +309,13 @@ Configuration), and the Keychain Secret bound to a `ProviderConfig.keychainKey`.
237309- Malformed ` config.json ` → app falls back to defaults gracefully; the settings
238310 window offers to reset to defaults.
239311
312+ #### Reliable Selection Reading (Dormant Accessibility Trees) ` [Source: specs/005-teams-ax-recovery/spec.md] `
313+
314+ - The wake-up call reports an error even when it works → the reported error code
315+ must not be treated as failure evidence (verified quirk; Principle III).
316+ - Repeated invocations while a retry window is active → the existing
317+ cancel-previous-run behavior applies unchanged.
318+
240319## Success Criteria
241320
242321#### Gemini Model Support ` [Source: specs/004-gemini-provider] `
@@ -299,6 +378,48 @@ parentheses.
299378- ** SC-018** (orig SC-004): A hotkey conflict during recording is flagged
300379 immediately and duplicate registration is prevented.
301380
381+ #### Reliable Selection Reading (Dormant Accessibility Trees) ` [Source: specs/005-teams-ax-recovery/spec.md] `
382+
383+ IDs renumbered on archival to avoid collision; original 005 identifier in
384+ parentheses.
385+
386+ - ** SC-019** (orig SC-001): After restarting Microsoft Teams, the first Overtype
387+ run against a Teams selection succeeds without any external warm-up, in at
388+ most 3 seconds more than a warm run.
389+ - ** SC-020** (orig SC-002): Runs against applications that already work (Outlook,
390+ native apps, warmed Teams) show no measurable latency increase (within normal
391+ variance) and no behavioral change.
392+ - ** SC-021** (orig SC-003): With nothing selected, the failure message is
393+ unchanged; in apps with an awake tree it stays instant, and in the cold-tree
394+ case the added delay stays within the bounded recovery window (about four
395+ seconds).
396+ - ** SC-022** (orig SC-004): Escape pressed during the recovery window cancels the
397+ run in under one second, with the target document untouched.
398+ - ** SC-023** (orig SC-005): The recorded manual acceptance for Teams in
399+ ` docs/compatibility.md ` passes from a cold Teams restart, twice in a row.
400+
401+ ## Assumptions
402+
403+ Recorded per feature; only assumptions that still govern the implemented system
404+ are kept.
405+
406+ #### Reliable Selection Reading (Dormant Accessibility Trees) ` [Source: specs/005-teams-ax-recovery/spec.md] `
407+
408+ - Teams' accessibility tree is dormant after a process restart, and setting the
409+ assistive-client flag wakes it even though the call reports an error
410+ (2026-08-02 diagnosis; re-verified by the manual acceptance procedure).
411+ - The retry configuration (24 x 150 ms, app-element first) is sufficient for the
412+ Teams and VS Code class of applications; no per-app tuning is provided. VS
413+ Code's recorded 13-second outlier is out of reach by design — a second press
414+ covers it.
415+ - Setting the wake-up flags only on the failure path is an acceptable trade-off
416+ for avoiding known side effects (window-resize glitches in some Electron apps)
417+ on apps that do not need them.
418+ - No configuration surface is added: the recovery is automatic and invisible;
419+ constants live in code, matching the tested values.
420+ - Writing (typing) behavior is out of scope for this recovery; it changes only
421+ how the selection is found and read.
422+
302423---
303424
304425### Revision: Archival 2026-08-02
@@ -325,3 +446,19 @@ parentheses.
325446 entities (referenced, not duplicated). Merged as ` [Source: specs/003-gui-settings] `
326447 sub-blocks. With this run, the project's four features (001, 002, 003, 004) are
327448 all archived.
449+
450+ ### Revision: Archival 2026-08-04 (Reliable Selection Reading / Dormant AX Trees)
451+
452+ - Reason: Archived ` specs/005-teams-ax-recovery ` . IDs renumbered to FR-035–FR-040
453+ and SC-019–SC-023; original 005 IDs annotated inline. Two of the feature's
454+ requirements were ** consolidated instead of appended** : orig FR-006
455+ (cancellation during the retry window) folded into FR-022 and orig FR-007
456+ (unchanged typed-error surface) folded into FR-023; both entries now carry two
457+ item-level source refs and their legacy 001 refs were upgraded in place. Two
458+ edge cases (context change mid-run; app that never exposes a selection) folded
459+ into the existing 001 entries for the same failure modes. A top-level
460+ ` ## Assumptions ` section was created, matching the spec template's ordering.
461+ - Recorded attempt count is ** 24 x 150 ms** , per the feature's FR-003, its plan,
462+ ` docs/compatibility.md ` , and ` AXHelpers.recoveryAttempts ` . The feature spec's
463+ Key Entities / Assumptions prose and its ` data-model.md ` still say the
464+ pre-amendment 12; those were left untouched as a stale-source note.
0 commit comments