Skip to content

Commit 15cddd1

Browse files
committed
docs(archive): archive 005-teams-ax-recovery into project memory
Merges the dormant-accessibility-tree recovery feature into the cumulative project memory now that it has landed on main. Requirements were renumbered to FR-035-FR-040 and SC-019-SC-023 to continue the existing sequences. Two of the feature's requirements were consolidated rather than appended: cancellation during the retry window folded into FR-022 and the unchanged typed-error surface into FR-023, so the main spec keeps one statement per capability instead of accumulating a per-feature restatement. Both entries now carry item-level source refs, and their legacy 001 refs were upgraded in place. Two edge cases folded into the existing 001 entries for the same failure modes. The archived attempt count is 24 x 150 ms, matching FR-003, the feature plan, docs/compatibility.md, and AXHelpers.recoveryAttempts. The feature spec's Key Entities/Assumptions prose and its data-model.md still carry the pre-amendment 12; that drift is recorded, not silently corrected, since fixing it belongs to the feature's own artifacts. CLAUDE.md previously documented the focused-element lookup as ending at five strategies, which is now stale: it describes the sixth escalation and why the pre-write re-check deliberately stays single-shot. The evidence-over-assumption constraint gains the read-side mirror quirk, where setting AXEnhancedUserInterface returns .notImplemented yet takes effect. Manual acceptance is recorded as PARTIAL (T007, T009, T011, T013 outstanding); this gates release, not archival. Documentation only; swift test passes with 64 tests, 0 failures.
1 parent a99ad58 commit 15cddd1

5 files changed

Lines changed: 238 additions & 9 deletions

File tree

‎.specify/memory/changelog.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,34 @@
22

33
## Merged Features Log
44

5+
### Reliable Selection Reading (Dormant Accessibility Trees) — 2026-08-04
6+
**Branch:** 005-teams-ax-recovery
7+
**Spec:** specs/005-teams-ax-recovery
8+
9+
_Note: FR/SC IDs renumbered to FR-035–FR-040 / SC-019–SC-023 in memory `spec.md`.
10+
Orig FR-006 and FR-007 were not appended: they were consolidated into the
11+
existing FR-022 and FR-023, which now carry two source refs each._
12+
13+
**What was added:**
14+
- US1 (P1): a cold-restarted Microsoft Teams recovers automatically — wake the
15+
dormant accessibility tree, retry the lookup within a bounded window, and
16+
complete the run instead of failing instantly with `noFocusedElement`.
17+
- US2 (P2): the fast path is untouched; no wake flags are set and no latency is
18+
added for apps whose lookup already succeeds.
19+
- US3 (P3): recovery exhaustion still ends in today's specific typed errors,
20+
within a bounded window, and Escape cancels promptly during the window.
21+
22+
**New Components:**
23+
- No new files or dependencies. `Support/AXHelpers.swift` gains
24+
`getFocusedElement(wakeDormantTree:)` plus private
25+
`wakeDormantAccessibilityTree(appElement:)` and `retryFocusLookup(appElement:)`;
26+
`Core/SelectionReader.swift` is the single opt-in call site.
27+
- Docs: `docs/compatibility.md` dormant-tree entry (wake-flag quirk, the
28+
misleading `.notImplemented` return code, the bounded recovery window).
29+
30+
**Tasks Completed:** 10/14 tasks (T007, T009, T011, T013 are manual acceptance
31+
items requiring the user at the machine; they gate release, not archival).
32+
533
### GUI Configuration Settings — 2026-08-02
634
**Branch:** 003-gui-settings
735
**Spec:** specs/003-gui-settings

‎.specify/memory/plan.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,8 +105,41 @@ Sources/Overtype/
105105
`emptyResponse`); `Providers/ProviderRegistry.swift` (one line wiring
106106
`.gemini` → `GeminiProvider`).
107107

108+
#### Reliable Selection Reading / Dormant AX Trees `[Source: specs/005-teams-ax-recovery]`
109+
110+
- **Approach**: A bounded recovery path inside the existing selection read,
111+
entered **only** after all five existing lookup strategies fail. No new files,
112+
no new dependency, no configuration surface.
113+
- **Edits**: `Sources/Overtype/Support/AXHelpers.swift` —
114+
`getFocusedElement(wakeDormantTree: Bool = false)` plus two private helpers,
115+
`wakeDormantAccessibilityTree(appElement:)` and `retryFocusLookup(appElement:)`;
116+
`Sources/Overtype/Core/SelectionReader.swift` — the single opt-in call site
117+
(`wakeDormantTree: true`).
118+
- **Recovery sequence**: set `AXEnhancedUserInterface` and
119+
`AXManualAccessibility` to true on the target app element, discarding both
120+
returned `AXError` values; `AXUIElementSetMessagingTimeout(2.0)` on the app
121+
element and a fresh system-wide element; then 24 attempts at 150 ms,
122+
`try Task.checkCancellation()` first in each iteration, querying the app
123+
element's focused element before the system-wide one. An element with a
124+
non-empty selection returns immediately; a selection-less element is kept as a
125+
fallback candidate while retries continue. Constants live in
126+
`AXHelpers.recoveryAttempts` / `recoveryMessagingTimeoutSeconds`.
127+
- **Design decision — recovery is read-path only.** `ActionEngine`'s pre-write
128+
context re-check deliberately keeps single-shot behavior: by write time the
129+
tree is provably warm, and Principle II requires a changed context to abort
130+
fast rather than after seconds of retries.
131+
- **Verification**: system-boundary code, so no mock-based unit tests
132+
(Principle VIII). Validated by `specs/005-teams-ax-recovery/quickstart.md`
133+
scenarios B–E, recorded in `docs/compatibility.md`. **Manual acceptance is
134+
PARTIAL**: the single-press cold-Teams retest at 24 attempts, the native-app
135+
fast-path check, the failure-timing/Escape scenario, and the regression sweep
136+
are outstanding (tasks T007, T009, T011, T013).
137+
108138
### Configuration
109139

140+
- No configuration is added by the dormant-tree recovery: it is automatic and
141+
invisible, and its constants are compile-time values bound to the tested
142+
configuration (deliberately not exposed, to avoid untested combinations).
110143
- New provider kind wire value `"gemini"` in `config.json`. A Gemini provider
111144
block may omit `baseURL` (defaults to the Google v1beta base). The shipped
112145
default config is unchanged; Gemini is enabled via a documented README recipe.
@@ -133,9 +166,31 @@ Sources/Overtype/
133166
- `Tests/OvertypeTests/AppConfigTests.swift`: `kind: gemini` config decode.
134167
- Manual acceptance (`specs/004-gemini-provider/quickstart.md`, A1–A8) recorded
135168
in `docs/compatibility.md`. **Live acceptance is PENDING** and gates release.
169+
- Dormant-tree recovery adds **no** unit tests by design (system-boundary code,
170+
no new pure logic); the existing suite must stay green. Its verification is the
171+
manual procedure above.
136172

137173
## Known Gotchas (from research)
138174

175+
- **A dormant accessibility tree is not a permission problem.** After Microsoft
176+
Teams restarts, every AX query returns `noValue` in ~12 ms and the tree stays
177+
dormant until an assistive client announces itself. Diagnose this before
178+
suspecting a code regression or a revoked Accessibility grant.
179+
- **AX return codes are not evidence in either direction.** Setting
180+
`AXEnhancedUserInterface` on Teams returns `.notImplemented` (-25208) yet takes
181+
effect (read-back flips to true and the tree activates). This is the mirror of
182+
the known Teams write quirk, where a set call returns success and changes
183+
nothing. Never gate on the returned `AXError` at these sites.
184+
- **`AXManualAccessibility` covers a different app family.** Teams rejects it
185+
(`attributeUnsupported`); Electron apps (VS Code, Claude desktop) honor it.
186+
Setting both flags covers both families at no cost.
187+
- **Wake flags have side effects, so they stay on the failure path.**
188+
`AXEnhancedUserInterface` is the flag VoiceOver sets and has historically
189+
caused window-resize/zoom glitches in some Electron apps. It is set only for
190+
apps that are already unusable with Overtype, at most once per run. The state
191+
persists in the target process until that app restarts; no cleanup is
192+
attempted, which is the intended assistive-client behavior.
193+
139194
- **Endpoint colon must not be percent-encoded.** The `:generateContent` action
140195
suffix is built by string concatenation, not `URL.appendingPathComponent`,
141196
which would encode the colon and break the request.
@@ -164,3 +219,12 @@ converge stages with no violations. Outstanding: the manual acceptance
164219

165220
- Reason: Archived `specs/003-gui-settings`. Added the Settings GUI increment and
166221
pinned the `KeyboardShortcuts` dependency version (1.15.0). No new dependency.
222+
223+
### Revision: Archival 2026-08-04 (Reliable Selection Reading / Dormant AX Trees)
224+
225+
- Reason: Archived `specs/005-teams-ax-recovery`. Added the dormant-tree recovery
226+
increment, its four research gotchas, and a "no configuration added" note. No
227+
new dependency and no new module — the change is contained in
228+
`Support/AXHelpers.swift` with a one-line opt-in from `Core/SelectionReader.swift`,
229+
so the Project Structure tree is unchanged. Manual acceptance is recorded as
230+
PARTIAL (T007, T009, T011, T013 outstanding).

‎.specify/memory/spec.md‎

Lines changed: 143 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -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
197251
Configuration), 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

Comments
 (0)