From 5ed775b8abd322d578e4002c1033d5a0c4b83253 Mon Sep 17 00:00:00 2001 From: EtienneLescot Date: Sat, 22 Aug 2026 10:12:11 +0200 Subject: [PATCH 1/2] docs(testing): say who runs the manual e2e pass, and that a slice counts The checklist already told you to drive it with computer-use. What none of the three documents said is that an agent holding that mouse *is* the operator, so the pass kept getting handed back to a maintainer as "manual e2e required" - including by me, one message after cutting v1.10.0-rc.1, while I had the MCP available the whole time. "Manual" names the input, not the operator: real OS mouse and keyboard events, because injected clicks arrive below the OS hit-test and the HUD is input-transparent until a real cursor move lifts it. That constraint is about where the events come from, and computer-use satisfies it. So AGENTS.md now states the availability check (list_granted_applications) and what to say when the MCP is genuinely absent, which is the only case where the checklist really does fall to a human. It also states that a slice is a run. Every row in the results log so far covered a subset - one of them is marked Pass with a NOT-covered list attached - so pretending the file is all-or-nothing only discourages the partial runs that found every defect logged there. The bound is on silence, not on scope: a check not run is skipped with its reason, never passed, and the run exists only as a results-log row carrying build/tag, platform, and what was left out. release-and-secrets.md gets it at the promote step, where the gate actually bites and where promote.yml enforces nothing. Co-Authored-By: Claude Opus 5 --- AGENTS.md | 4 ++++ technical-documentation/engineering/release-and-secrets.md | 2 ++ technical-documentation/testing/manual-e2e-checklist.md | 2 ++ 3 files changed, 8 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 91483965f..e3ad3e0ec 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -85,6 +85,10 @@ every edit is the main way an agent turns a 5-minute task into a 30-minute one, This section is the *mechanics*. **What to actually run is [`technical-documentation/testing/manual-e2e-checklist.md`](technical-documentation/testing/manual-e2e-checklist.md)** — the capture-to-export pass, per-platform sections, and a results log to append to. Run it before promoting a release candidate and after any change to native capture, preview or export. For cursor work specifically, [`native-cursor-diagnostics.md`](technical-documentation/testing/native-cursor-diagnostics.md) gets you sidecars and reports without a full record-edit-export cycle. The checklist links back here for the mechanics below; the pairing only works if you know both halves exist. +**If the computer-use MCP is available to you, this pass is yours to run — offer it, don't hand it back.** "Manual" names the input (real OS mouse and keyboard events), not the operator; an agent holding that mouse satisfies every check in the file. So when the work calls for it — a change to native capture, preview or export, or a release candidate waiting on QA — say you can run it and run it, instead of closing with "manual e2e pass required" and leaving a maintainer to do what you were already equipped to do. `list_granted_applications` answers whether the MCP is there at all; if it is not, say *that* plainly, because then the checklist genuinely does fall to a human. + +**Run whatever slice was asked for.** The whole file is one option, not the only one: a single section, one platform block, or the three checks that cover the change you just made are all legitimate runs — every row in the results log so far is a partial. What is not legitimate is silence about the rest. A check you did not run is **skipped with its reason**, never passed, and the run only exists once it is a row in the results log carrying the build/tag, the platform, and what you did not cover. + **Launch the app** - Normal: `npm run dev` — Vite serves the renderer and `vite-plugin-electron` opens the Electron window. The main process logs `Global shortcut registered: CommandOrControl+Shift+O` when ready (Ctrl/Cmd+Shift+O toggles the HUD). diff --git a/technical-documentation/engineering/release-and-secrets.md b/technical-documentation/engineering/release-and-secrets.md index 4cde4187a..3ee37fc8a 100644 --- a/technical-documentation/engineering/release-and-secrets.md +++ b/technical-documentation/engineering/release-and-secrets.md @@ -32,6 +32,8 @@ Run `Promote RC to stable release` (`promote.yml`) with: The workflow validates the tag, closes the version milestone, checks out `release/vX.Y.Z`, changes `package.json` to the stable version, tags that branch tip, opens and rebase-merges a release-sync PR into `main`, explicitly dispatches `build.yml` at the stable tag, and announces the stable release. The build publishes signed/notarized artifacts when Apple credentials are complete; publication with `OPENSCREEN_RELEASE_TOKEN` emits the event that starts stable Homebrew, WinGet, Nix, and AUR workflows. +**Before dispatching it, the RC has to have been through [the manual end-to-end checklist](../testing/manual-e2e-checklist.md).** Nothing in `promote.yml` enforces that — it will promote an untested tag exactly as readily — so the gate is the operator. It is not a human-only gate either: the checks need real OS mouse and keyboard events, which an agent with the computer-use MCP supplies, so asking one to run the file (or just the sections a given RC put at risk) is a normal way to get it done. Mechanics and the rule on partial runs: [AGENTS.md](../../AGENTS.md#desktop-e2e-testing-with-computer-use). + ### Release branches (the contract) Every released version has **exactly one frozen branch**, named for the stable version, living from the first RC cut onward: diff --git a/technical-documentation/testing/manual-e2e-checklist.md b/technical-documentation/testing/manual-e2e-checklist.md index 4be4b4b0a..dd5c26306 100644 --- a/technical-documentation/testing/manual-e2e-checklist.md +++ b/technical-documentation/testing/manual-e2e-checklist.md @@ -2,6 +2,8 @@ This checklist covers the real desktop capture-to-export path: the parts that unit, browser, and Playwright tests cannot exercise, including real screen capture, a physical webcam, the system tray, the native compositor, and export. Run it before promoting a release candidate and after any change to native capture, preview, or export. +**"Manual" is about the input, not the operator.** These checks need real OS mouse and keyboard events, not a human hand — so an agent with the computer-use MCP runs them, on demand, and a request for one section after a targeted change is as much a run as the whole file before a promote. Availability check and the rule on partial runs: [AGENTS.md](../../AGENTS.md#desktop-e2e-testing-with-computer-use). + Sections marked **v1.8.0** cover what this release changed: chat-driven editing through the agent tool set, clip-anchored modifiers, local transcription, the macOS Metal compositor, and the new effect controls. Run the whole file for a release candidate; the v1.8.0 sections are the ones with no prior release to fall back on. ## How to run this From a4e5c11de38fd7ce8d089e19cb9f61c86e2b3a51 Mon Sep 17 00:00:00 2001 From: EtienneLescot Date: Sat, 22 Aug 2026 10:18:07 +0200 Subject: [PATCH 2/2] docs(testing): keep the promote gate at the whole file Review on #461 caught that the parenthetical I added to release-and-secrets.md - "or just the sections a given RC put at risk" - weakened a rule the checklist already had. Its opening says to run the whole file for a release candidate, and nothing about a slice being a legitimate run was meant to touch that: the slice rule is for verifying a change, not for clearing a promotion. The results log is the argument. Webcam PiP, microphone, GIF and the AI sections have been scoped out of every run recorded there, so "the sections this RC puts at risk" is exactly the judgement that keeps missing them - which is the failure mode a whole-file gate exists to prevent. Both documents now say a Partial row is not a green light to dispatch. Co-Authored-By: Claude Opus 5 --- AGENTS.md | 2 ++ technical-documentation/engineering/release-and-secrets.md | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index e3ad3e0ec..4bd3a7dac 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -89,6 +89,8 @@ This section is the *mechanics*. **What to actually run is [`technical-documenta **Run whatever slice was asked for.** The whole file is one option, not the only one: a single section, one platform block, or the three checks that cover the change you just made are all legitimate runs — every row in the results log so far is a partial. What is not legitimate is silence about the rest. A check you did not run is **skipped with its reason**, never passed, and the run only exists once it is a row in the results log carrying the build/tag, the platform, and what you did not cover. +**A release candidate is the exception.** The checklist asks for the whole file before a promote, in its own opening, and that is not softened by anything above: a slice covers a *change*, never a promotion. Scope one down and the row you write says `Partial`, which is not a green light to dispatch `promote.yml`. + **Launch the app** - Normal: `npm run dev` — Vite serves the renderer and `vite-plugin-electron` opens the Electron window. The main process logs `Global shortcut registered: CommandOrControl+Shift+O` when ready (Ctrl/Cmd+Shift+O toggles the HUD). diff --git a/technical-documentation/engineering/release-and-secrets.md b/technical-documentation/engineering/release-and-secrets.md index 3ee37fc8a..0e794959f 100644 --- a/technical-documentation/engineering/release-and-secrets.md +++ b/technical-documentation/engineering/release-and-secrets.md @@ -32,7 +32,7 @@ Run `Promote RC to stable release` (`promote.yml`) with: The workflow validates the tag, closes the version milestone, checks out `release/vX.Y.Z`, changes `package.json` to the stable version, tags that branch tip, opens and rebase-merges a release-sync PR into `main`, explicitly dispatches `build.yml` at the stable tag, and announces the stable release. The build publishes signed/notarized artifacts when Apple credentials are complete; publication with `OPENSCREEN_RELEASE_TOKEN` emits the event that starts stable Homebrew, WinGet, Nix, and AUR workflows. -**Before dispatching it, the RC has to have been through [the manual end-to-end checklist](../testing/manual-e2e-checklist.md).** Nothing in `promote.yml` enforces that — it will promote an untested tag exactly as readily — so the gate is the operator. It is not a human-only gate either: the checks need real OS mouse and keyboard events, which an agent with the computer-use MCP supplies, so asking one to run the file (or just the sections a given RC put at risk) is a normal way to get it done. Mechanics and the rule on partial runs: [AGENTS.md](../../AGENTS.md#desktop-e2e-testing-with-computer-use). +**Before dispatching it, the RC has to have been through [the manual end-to-end checklist](../testing/manual-e2e-checklist.md).** Nothing in `promote.yml` enforces that — it will promote an untested tag exactly as readily — so the gate is the operator. It is not a human-only gate either: the checks need real OS mouse and keyboard events, which an agent with the computer-use MCP supplies, so asking one to run it is a normal way to get it done. For a promote that means the **whole file**, not a risk-picked subset — the checklist asks for it in its own opening, and its results log shows why: webcam PiP, microphone, GIF and the AI sections have been scoped out of every run recorded so far, so "the sections this RC puts at risk" is precisely the judgement that keeps missing them. A `Partial` row is not a green light to dispatch. Mechanics and the rule on partial runs: [AGENTS.md](../../AGENTS.md#desktop-e2e-testing-with-computer-use). ### Release branches (the contract)