browser-automation-skill 0.71.0

package/references/recipes/anti-patterns-tool-extension.md

@@ -0,0 +1,182 @@
+# Anti-patterns: tool extension
+
+When adding or modifying a tool adapter, these are the temptations to resist. Each is a real pattern an early contributor will reach for, with a clear WRONG / RIGHT shape and the SOLID-principle reasoning.
+
+## AP-1: Don't add adapter-specific checks to `browser-doctor.sh`
+
+```bash
+# WRONG — editing core to teach it about a new tool
+# scripts/browser-doctor.sh
+if ! command -v puppeteer >/dev/null 2>&1; then
+  warn "puppeteer not on PATH"
+  problems=$((problems+1))
+fi
+```
+
+```bash
+# RIGHT — adapter declares its own check; doctor aggregates
+# scripts/lib/tool/puppeteer.sh
+tool_doctor_check() {
+  if command -v puppeteer >/dev/null 2>&1; then
+    printf '{"ok":true,"binary":"puppeteer","version":"%s"}\n' "$(puppeteer --version)"
+  else
+    cat <<'EOF'
+{ "ok": false, "binary": "puppeteer", "error": "not on PATH",
+  "install_hint": "npm i -g puppeteer" }
+EOF
+  fi
+}
+```
+
+**SOLID:** SRP — `browser-doctor.sh` knows about framework-level state; `lib/tool/<tool>.sh` knows about its own binary. OCP — adding `puppeteer.sh` should never force an edit to a file in `scripts/` outside `lib/tool/`.
+
+## AP-2: Don't cross-call between adapters
+
+```bash
+# WRONG — adapter reaching into another adapter
+# scripts/lib/tool/obscura.sh
+tool_inspect() {
+  source "${LIB_TOOL_DIR}/playwright-cli.sh"
+  tool_inspect "$@"
+}
+```
+
+```bash
+# RIGHT — shared logic factors into a helper module
+# scripts/lib/inspect_helpers.sh   (NEW shared lib — sibling to lib/tool/)
+inspect_collect_console() { :; }
+
+# Both adapters source the helper; neither sources the other.
+# scripts/lib/tool/obscura.sh
+source "${BROWSER_SKILL_LIB}/inspect_helpers.sh"
+tool_inspect() { inspect_collect_console "$@"; }
+```
+
+**SOLID:** SRP + DIP — adapters are leaves. If two adapters need the same behavior, that behavior is a *shared concern* and lives in `scripts/lib/` (sibling to `lib/tool/`). Without this rule, the dependency graph stops being a tree.
+
+## AP-3: Don't declare routing precedence in an adapter (the Z-hybrid line)
+
+```bash
+# WRONG — adapter trying to claim "I'm the default for verb=audit"
+# scripts/lib/tool/puppeteer.sh
+tool_default_routes() {
+  cat <<'EOF'
+{ "audit": { "priority": 100 } }
+EOF
+}
+```
+
+```bash
+# RIGHT — adapter declares only what it CAN do; router decides who WINS
+# scripts/lib/tool/puppeteer.sh
+tool_capabilities() {
+  cat <<'EOF'
+{ "verbs": { "audit": { "flags": ["--lighthouse"] } } }
+EOF
+}
+
+# scripts/lib/router.sh   (one rule, one place — Path B in the recipe)
+rule_audit_verb() {
+  [ "${1:-}" = "audit" ] || return 1
+  printf 'puppeteer\taudit verb (Path B promotion)\n'
+}
+```
+
+**Why:** Routing precedence among peers is a global decision — when two adapters both claim audit, somebody has to break the tie, and centralizing that choice in `router.sh` lets a reviewer see the conflict in one diff. Decentralizing scatters precedence across N adapter files.
+
+## AP-4: Don't make a tool default in the same PR that adds it
+
+```diff
+# WRONG — single PR introduces tool AND promotes it
++ scripts/lib/tool/puppeteer.sh           (NEW)
++ tests/puppeteer_adapter.bats            (NEW)
++ tests/stubs/puppeteer                   (NEW)
++ tests/fixtures/puppeteer/               (NEW)
++ references/puppeteer-cheatsheet.md      (NEW)
+~ scripts/lib/router.sh                   (EDIT — adds rule_audit_verb -> puppeteer)
+~ tests/router.bats                       (EDIT)
+~ references/routing-heuristics.md        (EDIT)
+~ CHANGELOG.md                            (EDIT)
+```
+
+```diff
+# RIGHT — two PRs, separated by a soak window
+# PR #1 (Path A — ship dark, opt-in via --tool=puppeteer):
++ scripts/lib/tool/puppeteer.sh           (NEW)
++ tests/puppeteer_adapter.bats            (NEW)
++ tests/stubs/puppeteer                   (NEW)
++ tests/fixtures/puppeteer/               (NEW)
++ references/puppeteer-cheatsheet.md      (NEW)
+~ CHANGELOG.md                            (EDIT — [adapter] added, opt-in)
+
+# (one week later, after using --tool=puppeteer in real workflows)
+# PR #2 (Path B — promote to default):
+~ scripts/lib/router.sh                   (EDIT)
+~ tests/router.bats                       (EDIT)
+~ references/routing-heuristics.md        (EDIT)
+~ CHANGELOG.md                            (EDIT — [adapter] promoted)
+```
+
+**Why:** Process. A smaller PR is easier to revert. The "ship dark, then promote" pattern is the same hygiene any production system uses for feature flags.
+
+## AP-5: Don't hand-edit autogenerated files
+
+```bash
+# WRONG — manually adding a row to references/tool-versions.md
+$ vim references/tool-versions.md   # adds a "puppeteer" row by hand
+$ git add references/tool-versions.md && git commit
+# tests/lint.sh::ensure_docs_in_sync will fail in CI:
+# "tool-versions.md is stale; run scripts/regenerate-docs.sh"
+```
+
+```bash
+# RIGHT — let the generator do it; commit the generator's output
+$ vim scripts/lib/tool/puppeteer.sh   # implement tool_metadata + tool_doctor_check
+$ scripts/regenerate-docs.sh          # autogen edits the marked sections
+$ git add scripts/lib/tool/puppeteer.sh references/tool-versions.md SKILL.md
+$ git commit
+```
+
+**SOLID:** DRY + drift-prevention. The adapter's `tool_metadata()` is the single source of truth; any hand-edit to a generated file creates a second source that will go stale.
+
+## AP-6: Don't pollute the parent-shell namespace from adapter file scope
+
+```bash
+# WRONG — readonly globals at adapter file scope without a namespace prefix
+# scripts/lib/tool/puppeteer.sh
+readonly TIMEOUT=30
+readonly DEFAULT_VIEWPORT='1280x800'
+# ... tool_open uses $TIMEOUT
+```
+
+```bash
+# RIGHT — namespace the adapter's globals so they cannot collide
+# scripts/lib/tool/puppeteer.sh
+readonly _BROWSER_TOOL_PUPPETEER_TIMEOUT=30
+readonly _BROWSER_TOOL_PUPPETEER_DEFAULT_VIEWPORT='1280x800'
+# ... tool_open uses $_BROWSER_TOOL_PUPPETEER_TIMEOUT
+```
+
+**Why:** Encapsulation. The current loading model only sources one adapter per parent shell, so collision is unlikely today — but a future verb that consults two adapters in the same shell would clobber `TIMEOUT`. Prefix-namespacing makes globals private without ceremony.
+
+## AP-7: Don't accept secrets in argv
+
+`--secret-stdin` only. Lint and `tests/argv_leak.bats` enforce. A password on the command line is visible to `ps`, the shell history, and any tracing tool that sees argv. Always pipe secrets via stdin.
+
+## AP-8: Don't run network calls at adapter file-source time
+
+Sourcing must be cheap and pure. `command -v <binary>` is fine; running the binary at source time is not. The framework sources adapters dozens of times per CI run (once per subshell aggregation in doctor + lint). A network call at file-source time multiplies that cost.
+
+## AP-9: Don't test only the happy path
+
+Every `tests/<tool>_adapter.bats` must cover:
+- Declaration-presence of all 11 required functions.
+- `tool_capabilities()` returns valid JSON.
+- Unsupported-op exit-41 path (at least one verb that returns 41).
+- At least one happy path via the stub binary.
+
+## See also
+
+- [add-a-tool-adapter recipe](add-a-tool-adapter.md)
+- [extension model spec §9](../../docs/superpowers/specs/2026-04-30-tool-adapter-extension-model-design.md)
+- [token-efficient adapter output spec](../../docs/superpowers/specs/2026-05-01-token-efficient-adapter-output-design.md)

package/references/recipes/body-bytes-not-body.md

@@ -0,0 +1,139 @@
+# Recipe: `body_bytes`, not `body`, in replies
+
+When a verb ingests caller-supplied content (HTTP body, large blob, multi-line text), ship the **byte length** in the reply — not the content itself. Avoids re-emitting agent-supplied data into stdout / logs / terminal capture / Claude transcript.
+
+## When to use this recipe
+
+Use this whenever a verb takes content via `--content`, `--body`, `--data`, `--*-stdin`, or any flag that ingests bytes the agent typed and the verb forwards downstream. Already shipped:
+
+- `scripts/browser-route.sh` + `scripts/lib/node/chrome-devtools-bridge.mjs` (Phase 6 part 7-ii) — `route fulfill --body` / `--body-stdin`. Reply has `body_bytes`, not `body`.
+- `scripts/lib/node/chrome-devtools-bridge.mjs::runStatefulViaDaemon` (fill case, line ~432) — defensively scrubs `text` from the reply before emitting (related: privacy-canary handles the stronger secrets case).
+
+Phase 7 capture-pipeline candidates: any sanitizer-output reply that shows the agent how much got redacted.
+
+Do NOT use this recipe for:
+- Replies whose **shape requires** the content (e.g. `extract --selector` returns the matched element's textContent — that's the whole point of the verb). The contract is *return what was extracted*, not *return how many bytes were extracted*.
+- Secret-bytes (passwords, tokens). Those want **zero** reflection — see `privacy-canary.md`. Even `body_bytes` could leak something via length-side-channel for short secrets.
+
+## The pattern
+
+```javascript
+// WRONG — echo the body in the reply
+return {
+  verb: 'route',
+  action: 'fulfill',
+  pattern: msg.pattern,
+  status: msg.status,
+  body: msg.body,        // <-- agent-supplied content, now in stdout
+  rule_count: routeRules.length,
+};
+```
+
+```javascript
+// RIGHT — ship a length contract
+return {
+  verb: 'route',
+  action: 'fulfill',
+  pattern: msg.pattern,
+  fulfill_status: msg.status,
+  body_bytes: Buffer.byteLength(msg.body, 'utf8'),
+  rule_count: routeRules.length,
+};
+// body itself stays in the daemon's routeRules; never re-emitted.
+```
+
+Source of truth: `scripts/lib/node/chrome-devtools-bridge.mjs::case 'route'` (the fulfill branch).
+
+## Why the agent doesn't need the body back
+
+The agent **just sent** the body. They have it. The reply's job is to confirm:
+- That the request was accepted (`status: 'ok'`).
+- That it landed where intended (`pattern`, `rule_count`).
+- That the bytes the daemon received match what they sent (`body_bytes`).
+
+A length match is sufficient evidence that nothing got truncated by transport. If the agent suspects encoding corruption, they can `printf '%s' BODY | wc -c` and compare. They never needed the body echoed.
+
+## Why echoing is actively bad
+
+1. **Stdout is the Claude transcript.** Every echoed byte is a token the model rereads on the next turn. A 50KB JSON mock body bloats context for zero gain.
+2. **Logs persist.** If the user pipes the verb to `tee log.txt` or runs under `script(1)`, the body lands on disk in plain text. The daemon's in-memory store is a deliberate scoping decision; echoing undoes it.
+3. **Terminal-recording tools capture stdout.** Asciinema, screen recordings of demos, even `tmux` capture-pane all see whatever lands on stdout.
+4. **Convention sets expectations.** Once one verb echoes content, the next maintainer assumes that's the contract and adds another. Establishing "we ship lengths, not content" as the norm prevents the drift.
+
+## Why `Buffer.byteLength`, not `body.length`
+
+```javascript
+// WRONG — JS string length is code units, not bytes
+body_bytes: msg.body.length
+// '🔒'.length === 2 (UTF-16 surrogate pair)
+// '🔒' as utf-8 is 4 bytes
+```
+
+```javascript
+// RIGHT — count bytes, not code units
+body_bytes: Buffer.byteLength(msg.body, 'utf8')
+```
+
+If the agent's `printf | wc -c` says 4 and the reply's `body_bytes` says 2, that looks like data loss when it's just a counting-units mismatch. Always count in the same unit the agent will count in (bytes, not chars).
+
+Bash equivalent (for strings the bash verb script measures):
+
+```bash
+# WRONG — only correct for ASCII
+body_bytes="${#body_inline}"
+
+# RIGHT — measure bytes via wc
+body_bytes="$(printf '%s' "${body_inline}" | wc -c | tr -d ' ')"
+```
+
+`scripts/browser-route.sh:107` uses `${#body_inline}` only for the dry-run / inline-body case where the bash side already knows the bytes won't surprise; the daemon-side authoritative count uses `Buffer.byteLength`. For new verbs, prefer `wc -c` bash-side.
+
+## Defense in depth: also scrub upstream
+
+The bridge daemon's `route` reply is one layer. The fill verb's similar concern (`scripts/lib/node/chrome-devtools-bridge.mjs:432`) shows the defensive-scrub layered idiom:
+
+```javascript
+const reply = await ipcCall({ verb: 'fill', ref, text });
+// Defensive: scrub any echoed text from the reply before emitting.
+if (reply && typeof reply === 'object') delete reply.text;
+emitReply(reply);
+```
+
+Even if the daemon child accidentally puts `text` into the reply, the bridge strips it on the way out. **Two layers** because either layer can be edited carelessly; both wrong at the same time is the regression that ships.
+
+## What about echoing for `--dry-run`?
+
+Dry-run is the **one** justified case for surfacing the body — the agent asked "what would happen?" without committing. Even there, ship `body_bytes` plus an excerpt with explicit truncation, never the full body:
+
+```bash
+# dry-run summary
+emit_summary verb=route ... \
+             fulfill_status="${status_code}" \
+             body_bytes="${body_bytes}" \
+             body_excerpt="$(printf '%s' "${body_inline}" | head -c 80)" \
+             body_truncated="$([ "${body_bytes}" -gt 80 ] && echo true || echo false)"
+```
+
+`browser-route.sh` doesn't ship the excerpt today. Add it in a follow-up if dry-run UX feedback asks for it.
+
+## Checklist for any new content-ingesting verb
+
+```
+1. Reply object has `<thing>_bytes` (length), not `<thing>` (content).
+2. Daemon-child stores the content in the slot it was meant for; reply
+   surface is purely confirmation.
+3. Use Buffer.byteLength (Node) or wc -c (bash) — never .length on strings.
+4. If the verb routes through a bridge, add a defensive `delete reply.<thing>`
+   on the way out (see fill verb precedent).
+5. Test that asserts the byte-length contract: roundtrip a body with a known
+   non-ASCII character; confirm body_bytes matches `printf | wc -c`.
+6. NEVER echo the content even in error replies — error UX is the message
+   string, not the offending payload.
+```
+
+## See also
+
+- `scripts/lib/node/chrome-devtools-bridge.mjs::case 'route'` — fulfill branch.
+- `scripts/lib/node/chrome-devtools-bridge.mjs:432` — fill defensive scrub.
+- [Privacy canary recipe](privacy-canary.md) — stronger discipline for credential bytes.
+- [Path security recipe](path-security.md) — sister pattern for filesystem inputs.

package/references/recipes/cache-write-security.md

@@ -0,0 +1,210 @@
+# Recipe: Cache-write security
+
+A discipline for any verb that writes learned state to disk based on caller-supplied bytes. Codifies the contract that Phase 11 part 1's memory cache (`scripts/lib/memory.sh` + `scripts/browser-do.sh`) ships with: verbs that turn agent input into persistent cache state are a different security shape from verbs that read state, and they need defenses the read side doesn't.
+
+## When to use this recipe
+
+Use this **whenever you add a verb that persists caller-supplied selectors, intents, URL patterns, or other free-text agent input as cache/memory state read by future invocations**. Examples already shipped:
+
+- `scripts/browser-do.sh record` — Phase 11 part 1-ii; writes `(intent, selector, url_pattern)` triples to `~/.browser-skill/memory/<site>/`.
+- `scripts/browser-do.sh --intent` (cache-hit success path) — Phase 11 part 1-ii/iii; bumps `success_count` + records `pattern → archetype` mapping on dispatch success.
+- `scripts/browser-do.sh --intent` (cache-hit failure path, exit 11/13) — Phase 11 part 1-iii; increments `fail_count` toward H1 disable threshold.
+
+Do NOT use this recipe for:
+- Read-side verbs (lookup, list, show) — they don't persist new state; the privacy invariant is "don't echo what's already on disk", which is `privacy-canary.md`'s domain.
+- Captures (Phase 7) — they persist *observed* page state, not cache mappings; sanitization is `sanitize.sh`'s job, not the cache-write contract.
+- Sites profile / credentials / sessions (Phase 1–4) — these store explicit user-registered material; the user typed it deliberately. Cache writes happen *incidentally* during agent execution, which is what makes the security shape different.
+
+## The five rules
+
+### Rule 1 — Whitelist the cache-write surface
+
+Never accept a caller-supplied **verb name** that you'll dispatch (or store) without enumerating allowed targets in code.
+
+```
+WRONG — accept any verb name the caller supplies
+case "${arg_verb}" in
+  *) bash "${SCRIPT_DIR}/browser-${arg_verb}.sh" --selector "${cached}" ;;
+esac
+```
+
+```
+RIGHT — explicit constant whitelist; reject everything else
+readonly DO_VERB_WHITELIST=(click)   # v1: only click takes --selector
+_verb_in_whitelist() {
+  local needle="$1" v
+  for v in "${DO_VERB_WHITELIST[@]}"; do
+    [ "${v}" = "${needle}" ] && return 0
+  done
+  return 1
+}
+_verb_in_whitelist "${arg_verb}" \
+  || die "${EXIT_USAGE_ERROR}" "browser-do: --verb '${arg_verb}' not in whitelist (allowed: ${DO_VERB_WHITELIST[*]})"
+```
+
+Why: a caller-supplied verb name dispatching to `bash scripts/browser-${arg_verb}.sh` lets a typo silently route to the wrong verb (`fil` → file-not-found vs `fill` actually firing); worse, lets a hostile prompt trick the agent into invoking credential-handling verbs (`creds-show`, `extract`, `audit`) under the cache-hit fast path. Whitelist is constant; reviewers can grep it; new verbs join the whitelist by an explicit code change with reviewable rationale.
+
+Reference: `scripts/browser-do.sh::DO_VERB_WHITELIST` + `tests/browser-do.bats::4`.
+
+### Rule 2 — Refuse cache writes containing credential sentinels
+
+Cache writes carry caller-supplied free-text (intent phrases, selectors). If an agent accidentally inlines credential bytes into those args, they hit disk in the cache and survive across sessions. Refuse with a fast-fail.
+
+```
+WRONG — store whatever the caller passed
+memory_record "${site}" "${arch}" "${intent}" "${selector}"
+# Caller wrote intent="type password 'mySecret123'" → "mySecret123" persists.
+```
+
+```
+RIGHT — refuse on sentinel-shaped content
+readonly CANARY_SENTINEL='PASSWORD-CANARY'
+_canary_check() {
+  local field="$1" value="$2"
+  if printf '%s' "${value}" | grep -qF -- "${CANARY_SENTINEL}"; then
+    die "${EXIT_BLOCKLIST_REJECTED}" "browser-do: refused — ${field} contains canary sentinel '${CANARY_SENTINEL}'"
+  fi
+}
+_canary_check "intent"   "${arg_intent}"
+_canary_check "selector" "${arg_selector}"
+memory_record "${site}" "${arch}" "${arg_intent}" "${arg_selector}"
+```
+
+This is **not a real secret detector** — entropy scanning, real password-format detection, and the broader regex-zoo of credential patterns are out of scope for this recipe. The sentinel:
+
+- Lets bats inject `PASSWORD-CANARY` into intent or selector, assert exit `EXIT_BLOCKLIST_REJECTED (28)`, AND assert the cache file is untouched on disk. That's the **regression** safety net.
+- Forces the production code to have a refusal codepath at all, instead of unconditionally writing whatever shows up.
+
+Real entropy/format-based detection is a future hardening pass. Document it as such in the recipe-doc + plan-doc.
+
+Reference: `scripts/browser-do.sh::_canary_check` + `tests/browser-do.bats::24,25`.
+
+### Rule 3 — Cache writes are best-effort; never taint the action's exit code
+
+The action (clicking, filling, navigating) is the user's actual intent. The cache-write is an *opportunistic side effect* that improves future runs. **Cache freshness < action correctness.**
+
+```
+WRONG — cache failure surfaces as the verb's exit code
+memory_record "${site}" "${arch}" "${intent}" "${selector}" \
+  || die "${EXIT_GENERIC_ERROR}" "cache write failed"
+```
+
+```
+RIGHT — log and forge ahead
+if ! memory_record "${site}" "${arch}" "${intent}" "${selector}" 2>/dev/null; then
+  warn "browser-do: cache success_count update failed (best-effort; action exit unchanged)"
+fi
+```
+
+Why: a disk-full or perms-bug while writing the cache must not retroactively turn a successful click into an error the agent has to handle. The agent did the right thing; if the skill couldn't remember, that's the skill's problem to log, not the agent's problem to debug. The `warn:` line is observable to the user/reviewer; the action's exit code (and downstream agent decisions) stays correct.
+
+Reference: `scripts/browser-do.sh` cache-hit-success branch + post-dispatch failure-recording branch (both `warn:`-only on cache failure).
+
+### Rule 4 — Self-heal failure-counting needs an exit-code whitelist
+
+If you wire failure counting into a verb (e.g. "fail 4 times → mark cached selector disabled"), **only specific exit codes drive the counter.** Counting any non-zero exit poisons the cache when the failure was environmental.
+
+```
+WRONG — count any failure as a selector-fitness signal
+if [ "${dispatch_rc}" -ne 0 ]; then
+  memory_record_failure "${site}" "${arch}" "${intent}"
+fi
+```
+
+```
+RIGHT — whitelist the exit codes that genuinely indicate a selector miss
+elif [ "${dispatch_rc}" -eq "${EXIT_EMPTY_RESULT}" ] || [ "${dispatch_rc}" -eq "${EXIT_ASSERTION_FAILED}" ]; then
+  # 11 = element not found at selector; 13 = assertion failed (expected element absent).
+  # 30 (network), 42 (tool crash), 43 (timeout) are environmental — they would poison
+  # the cache if we counted them.
+  if ! memory_record_failure "${site}" "${arch}" "${intent}" 2>/dev/null; then
+    warn "browser-do: cache fail_count update failed (best-effort)"
+  fi
+fi
+```
+
+Why: a flaky network or a one-off tool crash shouldn't push a working selector toward disable. The cache is supposed to remember "this selector reliably finds the element"; only the kind of failure that would change that conclusion (the selector returning nothing; the assertion not matching) qualifies as evidence the cached value is stale.
+
+Pick the whitelist deliberately:
+- **In:** Exit codes that mean "the cached value was tried and its referent wasn't there." `EXIT_EMPTY_RESULT (11)` and `EXIT_ASSERTION_FAILED (13)` for Phase 11 part 1.
+- **Out:** Network errors, tool crashes, timeouts, session expiry, usage errors. Document the cutoff inline so future readers see the rule, not just the list.
+
+Reference: `scripts/browser-do.sh` post-dispatch elif branch + `tests/browser-do.bats::29,30,31` (covers in-whitelist 11+13 + out-of-whitelist 30).
+
+### Rule 5 — Lock the cache schema; don't store action-type
+
+Cache schema is **forever** (or schema-version-bump-forever). Frozen v1 shapes can only grow new fields, not change existing ones. The temptation to add a `verb` field per cached interaction so the cache can dispatch any verb on hit — *resist it*.
+
+```
+WRONG — cache stores (intent, selector, verb)
+{
+  "intent": "click delete",
+  "selector": "button.delete",
+  "verb": "click"               // <-- couples cache to verb-set; schema-bump on every new verb
+}
+```
+
+```
+RIGHT — cache stores (intent, selector); caller specifies verb per call
+{
+  "intent": "click delete",
+  "selector": "button.delete"
+}
+# Caller: browser-do --verb click --intent "click delete"
+# Same selector can serve hover, fill (with --text), etc. — orthogonal axis.
+```
+
+Why: storing verb-type in the cache forces a schema bump every time you add a new dispatchable verb. The cache becomes brittle to the verb set. Moving the verb axis out (caller passes `--verb` per call) keeps the cache stable across verb-set evolution, AND lets the same selector serve multiple actions naturally (the same `button.confirm` selector is clickable AND hoverable; storing it once is correct).
+
+Corollary: **don't store literal URLs**. Store *patterns*. URLs change every visit (`/devices/123` vs `/devices/124`); patterns generalize (`/devices/:id`). Storing the literal couples the cache to one entity instance; storing the pattern lets the cache hit across the whole archetype.
+
+Reference: archetype JSON shape in `scripts/lib/memory.sh::memory_save_archetype` + design doc 2026-05-08-phase-11-memory-design.md §3 M1.
+
+## What to test
+
+Each rule needs at least one bats case proving the contract holds:
+
+```
+1. Whitelist enforcement:        --verb ghost → exit EXIT_USAGE_ERROR
+2. Canary refusal (intent):      intent='PASSWORD-CANARY ...' → exit 28; cache untouched
+3. Canary refusal (selector):    selector='input[name=PASSWORD-CANARY]' → exit 28; cache untouched
+4. Best-effort write semantics:  (harder — needs a forced cache-write failure
+                                  to prove the action's exit code stays unchanged.
+                                  May be deferred to integration testing.)
+5. Self-heal in-whitelist:       dispatched verb exits 11 → fail_count++
+6. Self-heal in-whitelist:       dispatched verb exits 13 → fail_count++
+7. Self-heal out-of-whitelist:   dispatched verb exits 30 → fail_count UNCHANGED
+8. Schema stability:             new field added → existing fixtures still parse
+                                  (round-trip test in lib bats)
+```
+
+Sample placement (already shipped): `tests/browser-do.bats::4,12,13,29,30,31,32` (rules 1, 2, 3, 5, 6, 7, end-to-end). `tests/memory.bats::2,13` (rule 5 round-trip + self-heal D2 reset).
+
+## Why a per-recipe contract beats per-PR vigilance
+
+Phase 11 part 1 shipped over three PRs (1-i lib + 1-ii verb + 1-iii self-heal). Each PR had a plan-doc that locked decisions for that scope; the cumulative cache-write contract spans all three. **Without this recipe, a future PR adding a new cache-writing verb would have to re-derive the same five rules** by reading three plan-docs in sequence + the design doc. Recipes turn cumulative knowledge into a single grep-able artifact.
+
+Concretely: if a PR adds `browser-do --verb fill` after `fill` gains `--selector` adapter plumbing, the reviewer should be able to ask "did this PR honor the cache-write contract?" and check this file's five rules + the test placements without having to reconstruct the rationale from three months of git log.
+
+## Don't
+
+- **Don't** add fields that store user-typed values verbatim in the cache. Selectors are CSS strings (structurally bounded); intents are short natural-language phrases (no value bytes). If you need to cache a typed value (e.g. "remember the username for this site"), it's not a memory-cache concern — it's the **credentials backend** (Phase 4), with its own security envelope.
+- **Don't** widen the self-heal exit-code whitelist without explicit rationale. Adding code 22 ("session expired") looks reasonable but couples the cache to a different subsystem's failure mode; the cached selector is fine — the *session* needs renewing.
+- **Don't** cache across sites. Per-site memory is the boundary (design doc §12). A selector that works on `prod-app` may have a homonym on `staging` that means something different.
+- **Don't** auto-sanitize / strip sentinel bytes silently. Refuse with `EXIT_BLOCKLIST_REJECTED`. The agent's call site needs to know the cache write didn't happen so it doesn't assume a future hit; silent strip would create a "successful write that wrote nothing" failure mode that's worse than refusal.
+- **Don't** add `press` to the cache-dispatch whitelist via `--focus-selector` or similar target-flag retrofit. **`press` is structurally outside cache scope** — chrome-devtools-mcp's bridge `case 'press':` is target-less by design ("Stateless w.r.t. refMap — acts on the focused element or page"; `lib/node/chrome-devtools-bridge.mjs:1098`). The cache-friendly composition is: agent calls `browser-do --verb click --intent "focus input"` to land focus on the right element, then invokes `browser-press --key Enter` directly (no cache; relies on focus state from prior click). This composition uses the cache where it adds value (target resolution) and leaves press as a no-op-for-cache stateless keyboard event. Documented in selector-mode-select plan-doc as decision SS5 + selector-mode plumbing HANDOFF row.
+
+## Codified deferrals
+
+| Verb / surface | Status | Why |
+|---|---|---|
+| `press` cache dispatch | **deferred (option c — compose-with-click+press)** | Bridge designed target-less. Cache-friendly composition: cache `click "focus input"` then invoke `press` directly. Recommended over `--focus-selector` retrofit; no IPC schema bump needed. |
+| `hover`/`select` on playwright-lib | deferred (no demand) | Hover + select route exclusively to chrome-devtools-mcp per `lib/router.sh::rule_{hover,select}_default`. If routing ever expands, mirror PR #105's pattern (`runHover`/`runSelect` + IPC `case 'hover':`/`case 'select':` selector branch). |
+
+## See also
+
+- [Privacy canary recipe](privacy-canary.md) — sister pattern for read-side verbs that ingest secrets.
+- [Path security recipe](path-security.md) — how `~/.browser-skill/memory/` enforces 0700 dir + 0600 file modes (mirrored from the captures pipeline).
+- [Anti-patterns: tool extension](anti-patterns-tool-extension.md) — AP-7 (secrets-via-stdin), the broader pattern this recipe extends to cache-write surfaces.
+- Design doc: `docs/superpowers/specs/2026-05-08-phase-11-memory-design.md` §6 (memory + recipes integration), §12 (cross-site boundary), §3 H1 (self-heal threshold).
+- Phase 11 part 1 plan-docs: `2026-05-10-phase-11-part-1-{i,ii,iii}-*.md` — per-PR scope decisions that compose into this recipe.