docs(browser-debug): pane-first recipes for dialog/iframe/shadow (#2)

Align the shared workflow skill with Octopus pane agents: prefer the
user-visible pane, pre-arm dialogs, use f{seq}/e{n} frame refs, and
dual-leg highlight/locator tools.

core/checklists/release.md

@@ -93,5 +93,5 @@
 | 7.4 | `sync-public-assets.sh` 已跑：公共镜像 `Octopus/octopus-release` 的 `v{version}` release 有 12 资产 | ☐ | ☐ | 大 POST 出站不通时经服务器 localhost 中继 |
 | 7.5 | `sync-public-install.sh` 已跑：install/install.ps1/README 同步到镜像 main（注意 cp 目标是**根 README.md**，不是 scripts/ 副本） | ☐ | ☐ | |
 | 7.6 | `verify-public-sync.sh` PASSED | ☐ | ☐ | |
-| 7.7 | Desktop feed 双平台已派发（`desktop-feed.yml` dispatch ×2：beta/prod × win/linux），`latest.yml` 与 `latest-linux.yml` 的 `version:` == CLI 版本 | ☐ | ☐ | concurrency 组已按 platform 分离；资产字节数须与 feed 声明一致 |
+| 7.7 | Desktop feed 三腿已派发（mac 走 `desktop-mac.yml` dispatch；win/linux 各一次 `desktop-feed.yml` dispatch），`bun packages/desktop/script/verify-feed.ts --version <ver> --channel <beta|prod>` PASS（三平台 yml 全量校验：`latest.yml`/`latest-linux.yml`/`latest-mac.yml` 的 `version:` == CLI 版本 + size 对资产逐项核对 + 匿名可达） | ☐ | ☐ | #6378 起以 verify-feed.ts 为准（v0.31.0 漏腿事故 #6375 的 fail-loud 补丁）；concurrency 组已按 platform 分离；stable 通道 feed 缺失见 #6376 |
 | 7.8 | README 下载链接抽查（install 脚本 raw、资产直链、docs 相对链接）匿名可达 | ☐ | ☐ | v0.18 遗留 wiki 坏链由此发现 |

core/skills/browser-debug/SKILL.md

@@ -100,6 +100,25 @@ not by familiarity:
 | Keyboard navigation | `browser_press_key` | For tab order, focus rings, escape-to-close. |
 | Record a video / trace | `browser_start_tracing`, `browser_stop_tracing` | Heavy; use only when a bug is timing-sensitive and console+snapshot can't catch it. |
 
+## Pane-first recipe (prefer over headless)
+
+Default to the **user-visible browser pane** unless the task explicitly needs
+an isolated headless Chromium (`surface: "headless"`). Pane agents now match
+or exceed Playwright for the hard cases:
+
+| Need | Pane tool / pattern | Notes |
+| --- | --- | --- |
+| Open / bind pane | `browser_open` (default surface) | Never touch the user's pane from a headless-only intent — pass `surface: "headless"` or `browser_pane_release` first. |
+| Structure + refs | `browser_snapshot` | Open shadow is pierced; cross-origin iframes expose `f{seq}/e{n}` synthetic refs — prefer those over attr ids when acting into child frames. |
+| Act (click/type/…) | `browser_act` / `browser_act_batch` | Locators (`role=` / `text=` / …) walk open shadow. Cross-origin click/type route through CDP trusted events. |
+| Native dialogs | `browser_handle_dialog` **before** the act | Prefer `mode: "arm"` (or `act_batch.dialog_prearm`) so the pane parks the answer before the click that opens confirm/prompt — avoids the 1.5s auto-dismiss / widget-cancel race. Bind with `messageIncludes` when the page can raise multiple dialogs. Call `mode: "disarm"` if the trigger was cancelled. |
+| Highlight / locator | `browser_highlight`, `browser_generate_locator` | Dual-leg: both pane and headless. Use highlight to confirm the ref before a write. |
+| Failure recovery | re-snapshot + path candidates | Act/locator failures may return `pathCandidates` (frame/shadow path hints). Heal scores framePath so sibling iframes do not auto-heal across frames. |
+
+Headless remains the right tool for parallel CI-style isolation and when the
+user must not see the session. For interactive debug of `packages/app`, stay
+on the pane.
+
 ## Standard recipe — reproduce a UI bug
 
 Follow these steps in order. Do not skip the snapshot step: the `ref` it

core/skills/implement/SKILL.md

@@ -127,6 +127,20 @@ Rules:
 
 Each execution mode below defines its own Tester focus and any mode-specific orchestration overrides.
 
+**Producer test preflight** (before writing any test):
+
+1. **No absolute-path targets outside the test's own fixture/instance dir** — target fixtures or instance-relative paths instead. Where behavior is
+   platform-dependent (path resolution differs Windows/Linux), assert the
+   platform-specific expectation explicitly; a platform mismatch must fail,
+   never pass by accident.
+2. **Polling/wait-for loops must be bounded AND non-vacuous** — bound the
+   loop AND assert the body executed at least once (e.g. an iteration
+   counter asserted after the loop), so a timeout-cut never yields a false
+   green.
+
+Anchor: CI job 112302 (PR [org-internal #6409] first head red — nonexistent absolute path
+drill + 15s-bound vacuous loop).
+
 ## Greenfield vs. Brownfield
 
 **Greenfield** (new project): Create new files following the design. Project conventions are defined by the design document.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "octopus-workflow",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Standalone workflow core: provider-neutral agent workflow corpus (skills / rules / checklists / templates / schemas) with drift guards, extracted from the octopus agent platform.",
   "license": "MIT",
   "private": false,