opendevbrowser 0.0.15 → 0.0.17

package/skills/opendevbrowser-best-practices/SKILL.md

@@ -1,122 +1,296 @@
 ---
 name: opendevbrowser-best-practices
-description: This skill should be used when the user asks to "automate a browser flow", "write an OpenDevBrowser script", "use snapshot refs", "extract page content", or "debug browser automation".
-version: 1.1.0
+description: This skill should be used when the user asks to design or run OpenDevBrowser provider workflows, scraping pipelines, QA/debug automation, parity checks across modes, or resilient browser operations with codified scripts and artifacts.
+version: 2.5.0
 ---
 
 # OpenDevBrowser Best Practices
 
-Use this guide to produce reliable, script-first automation with minimal retries and predictable output.
+This is the primary battery pack for OpenDevBrowser operations.
+
+Use this skill when you need:
+- provider-oriented workflows (`web`, `community`, `social`),
+- script-first runbooks,
+- parity across `managed`, `extension`, `cdpConnect`,
+- diagnostics for QA/debug (`console`, `network`, trace context),
+- safe write flows with explicit policy notice.
+
+## Pack Contents
+
+- `artifacts/provider-workflows.md` — canonical provider execution flows.
+- `artifacts/parity-gates.md` — mode/surface parity matrix and acceptance gates.
+- `artifacts/debug-trace-playbook.md` — diagnostics workflow and trace bundle model.
+- `artifacts/fingerprint-tiers.md` — hardening tiers and when to use each.
+- `artifacts/macro-workflows.md` — macro design and expansion standards.
+- `artifacts/browser-agent-known-issues-matrix.md` — known browser-agent failure modes mapped to required controls.
+- `artifacts/command-channel-reference.md` — CLI/tool/`/ops`/`/canvas`/`/cdp` surface map plus cross-agent skill-sync targets.
+- `artifacts/canvas-governance-playbook.md` — `/canvas` preflight, blocker, and feedback-evaluation guidance.
+- `assets/templates/mode-flag-matrix.json` — mode + flag verification template.
+- `assets/templates/ops-request-envelope.json` — `/ops` request envelope template.
+- `assets/templates/cdp-forward-envelope.json` — `/cdp` relay envelope template.
+- `assets/templates/robustness-checklist.json` — shared issue-status checklist for workflow robustness audits.
+- `assets/templates/surface-audit-checklist.json` — docs/surface audit checklist template.
+- `assets/templates/canvas-handshake-example.json` — canonical `/canvas` handshake example.
+- `assets/templates/canvas-generation-plan.v1.json` — required `canvas.plan.set` request skeleton.
+- `assets/templates/canvas-feedback-eval.json` — target-attributed feedback evaluation checklist.
+- `assets/templates/canvas-blocker-checklist.json` — machine-readable blocker and warning audit map.
+- `scripts/odb-workflow.sh` — prints codified command sequences by workflow.
+- `scripts/run-robustness-audit.sh` — validates workflow skill coverage against known issue IDs.
+- `scripts/validate-skill-assets.sh` — validates required artifacts/templates.
+
+## Fast Start
+
+1. Validate the skill pack:
+
+```bash
+./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh
+```
 
-## Core Operating Model
+2. Pick a workflow:
 
-Follow the loop strictly:
+```bash
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh provider-crawl
+```
 
-1. Establish or attach a session.
-2. Capture `opendevbrowser_snapshot`.
-3. Select refs from that snapshot.
-4. Execute one or more actions using refs.
-5. Re-snapshot after navigation or major DOM change.
+3. Execute the printed sequence with session-specific values.
 
-Prefer refs over raw selectors. Refs are more stable across dynamic UI changes.
+4. Surface full controls directly from CLI help when auditing runtime accessibility:
 
-## Session Strategy
+```bash
+npx opendevbrowser --help
+npx opendevbrowser help
+```
 
-Choose mode deliberately:
+5. Run robustness coverage checks across workflow skills:
 
-- Use managed mode for deterministic, isolated runs.
-- Use extension mode when existing logged-in tabs or profile state are required.
-- Use CDP connect mode only when attaching to a pre-launched browser is required.
+```bash
+./skills/opendevbrowser-best-practices/scripts/run-robustness-audit.sh
+```
 
-Example launch patterns:
+## Agent Sync Targets
 
-```text
-opendevbrowser_launch noExtension=true
-opendevbrowser_launch waitForExtension=true
-opendevbrowser_connect wsEndpoint="ws://127.0.0.1:9222/devtools/browser/<id>"
-```
+Skill-pack installation and discovery are synchronized for:
+- `opencode` (`~/.config/opencode/skill`, project `./.opencode/skill`)
+- `codex` (`$CODEX_HOME/skills` fallback `~/.codex/skills`, project `./.codex/skills`)
+- `claudecode` (`$CLAUDECODE_HOME/skills` or `$CLAUDE_HOME/skills` fallback `~/.claude/skills`, project `./.claude/skills`)
+- `ampcli` (`$AMPCLI_HOME/skills` or `$AMP_CLI_HOME/skills` or `$AMP_HOME/skills` fallback `~/.amp/skills`, project `./.amp/skills`)
 
-## Snapshot Discipline
+Legacy compatibility aliases `claude` and `amp` are preserved in installer target metadata.
 
-Capture snapshots in the format needed by the current task:
+## Required Operating Rules
 
-- Use `format="outline"` for broad page state.
-- Use `format="actionables"` for interaction planning.
-- Use `maxChars` and `cursor` to page large pages instead of requesting oversized snapshots.
+- Prefer refs from `opendevbrowser_snapshot` over raw selectors.
+- Use one action per decision loop: snapshot -> action -> snapshot.
+- Keep a single correlation context (`requestId`, `sessionId`) across a run.
+- Run the same workflow shape across all three modes before claiming parity.
+- Default to read/research workflows. Social posting probes remain disabled unless explicitly requested via matrix opt-in (`--include-social-posts`).
+- Apply rate-limit/backoff discipline (`Retry-After` aware) whenever 429 pressure appears.
+- Re-check extension readiness on resume when a run crosses idle windows.
 
-```text
-opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
-```
+## Parallel Operations (Reliable As-Is)
 
-## Action Sequencing
+- Safe parallelism today is `session-per-worker` (one session per page/tab command stream).
+- Keep each session single-writer for target/page actions; run commands serially inside that session.
+- Do not run independent concurrent streams that alternate `target-use` within one session.
+- Use default extension `/ops` for relay-backed concurrency; use `/cdp` only for legacy compatibility paths.
+- For managed parallel runs with persisted profiles, use unique profile paths per session (or disable persistence) to avoid profile lock collisions.
+- Treat extension headless attempts (`--extension-only --headless`) as expected `unsupported_mode`; route headless workloads through managed/cdpConnect instead.
+- Before extension-mode runs, preflight `npx opendevbrowser status --daemon` and require `extensionConnected=true` plus `extensionHandshakeComplete=true`.
 
-Stabilize before interacting:
+Operational references:
+- `artifacts/provider-workflows.md` (see Workflow E)
+- `scripts/odb-workflow.sh parallel-multipage-safe`
+- `docs/CLI.md` (concurrency semantics)
+- `docs/SURFACE_REFERENCE.md` (transport and policy constraints)
+- `docs/TROUBLESHOOTING.md` (parallel crosstalk and profile-lock remediation)
 
-- After `goto` or click-driven navigation, run `opendevbrowser_wait`.
-- Wait on `until="networkidle"` for API-heavy pages.
-- Wait on `ref` + `state` for specific element readiness.
+## Known-Issue Robustness Baseline
+
+- Source matrix: `artifacts/browser-agent-known-issues-matrix.md`
+- Reusable checklist: `assets/templates/robustness-checklist.json`
+- Coverage validator: `scripts/run-robustness-audit.sh`
+
+Use issue IDs from the matrix in each workflow skill (`ISSUE-01` ... `ISSUE-12`) so robustness checks stay machine-verifiable and DRY.
+
+## Provider Workflows (Codified)
+
+### Provider Search Workflow
+
+Goal: deterministic query + extraction from one provider.
 
 ```text
+opendevbrowser_launch noExtension=true
+opendevbrowser_goto sessionId="<session-id>" url="<provider-search-url>"
 opendevbrowser_wait sessionId="<session-id>" until="networkidle"
-opendevbrowser_wait sessionId="<session-id>" ref="<target-ref>" state="visible"
+opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
+# extract targeted results using refs
+opendevbrowser_network_poll sessionId="<session-id>" max=50
 ```
 
-For multi-step interactions, batch deterministic steps with `opendevbrowser_run`.
+### Provider Crawl Workflow
+
+Goal: multipage fetch + extraction with bounded depth.
 
 ```text
-opendevbrowser_run sessionId="<session-id>" steps=[{"action":"goto","args":{"url":"https://example.com"}},{"action":"wait","args":{"until":"networkidle"}},{"action":"snapshot","args":{"format":"actionables"}}]
+opendevbrowser_launch noExtension=true
+opendevbrowser_goto sessionId="<session-id>" url="<seed-url>"
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
+# capture links/data, enqueue next pages in host logic
+opendevbrowser_scroll sessionId="<session-id>" dy=1000
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
 ```
 
-## Extraction and Output Control
-
-Keep output scoped and cheap:
+### QA Debug Workflow
 
-- Extract only the needed node text with `opendevbrowser_dom_get_text`.
-- Use `opendevbrowser_dom_get_html` only for small targeted fragments.
-- Use `opendevbrowser_get_attr` and `opendevbrowser_get_value` for structured field data.
+Goal: isolate frontend regressions quickly.
 
 ```text
-opendevbrowser_dom_get_text sessionId="<session-id>" ref="<content-ref>"
-opendevbrowser_get_attr sessionId="<session-id>" ref="<input-ref>" name="aria-invalid"
+opendevbrowser_snapshot sessionId="<session-id>" format="outline"
+opendevbrowser_console_poll sessionId="<session-id>" max=100
+opendevbrowser_network_poll sessionId="<session-id>" max=100
+opendevbrowser_screenshot sessionId="<session-id>"
 ```
 
-## Lightweight Diagnostics
+### Read-Only Social Validation Workflow
 
-Inspect runtime behavior only when required:
+Goal: validate authenticated read/search capability without posting.
 
-- Use `opendevbrowser_console_poll` to detect script/runtime errors.
-- Use `opendevbrowser_network_poll` to verify request outcomes.
-- Use `opendevbrowser_screenshot` for visual debugging artifacts.
+1. Connect and verify extension readiness (`extensionConnected` + handshake).
+2. Navigate/search target social surface.
+3. Capture `debug-trace-snapshot` and `network-poll` evidence.
+4. Record blocker/auth status only (no write action).
 
-```text
-opendevbrowser_console_poll sessionId="<session-id>"
-opendevbrowser_network_poll sessionId="<session-id>" max=50
-```
+## Workflow Router Script
 
-## Failure Recovery Order
+Use the router script to avoid retyping flows:
 
-When a step fails, recover in this order:
+```bash
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh provider-search
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh provider-crawl
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh qa-debug
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh social-readonly-check
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh parity-check
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh surface-audit
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh ops-channel-check
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh cdp-channel-check
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh mode-flag-matrix
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh robustness-audit
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh canvas-preflight
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh canvas-feedback-eval
+```
 
-1. Re-snapshot to refresh refs.
-2. Re-wait for load or element state.
-3. Retry action once with fresh refs.
-4. Change mode (managed vs extension) only if failure is mode-specific.
+## Modes and Surface Parity
 
-Avoid blind repeated retries against stale refs.
+Always run acceptance on:
+- Modes: `managed`, `extension`, `cdpConnect`
+- Surfaces: tool API, CLI, daemon RPC
 
-## Security and Safety Defaults
+Reference: `artifacts/parity-gates.md`
 
-- Keep CDP and relay endpoints local-only by default.
-- Do not place secrets in scripts, skill files, or logs.
-- Prefer minimal extraction over full-page dumps when handling sensitive pages.
+Parity gate test:
 
-## Ready-to-Use Flow Template
+```bash
+npm run test -- tests/parity-matrix.test.ts
+```
 
-```text
-opendevbrowser_launch noExtension=true
-opendevbrowser_goto sessionId="<session-id>" url="https://example.com"
-opendevbrowser_wait sessionId="<session-id>" until="networkidle"
-opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
-# interact with refs
-opendevbrowser_snapshot sessionId="<session-id>" format="outline"
+Real-world provider+mode scenario harness (soak replacement):
+
+```bash
+npm run build
+node scripts/provider-live-matrix.mjs --use-global-env --skip-live-regression --out artifacts/provider-live-realworld.json
 ```
+
+Surface inventory source of truth:
+- `docs/SURFACE_REFERENCE.md` (56 CLI commands, 49 tools, 38 `/ops` commands, 26 `/canvas` commands, `/cdp` envelope contracts; mirrored by `npx opendevbrowser --help` and `npx opendevbrowser help`)
+- `artifacts/command-channel-reference.md` (skill-pack operational digest)
+
+## Canvas Governance Handshake
+
+Use the design-canvas surface when the workflow needs persisted design documents, explicit governance state, preview tabs, or overlay selection.
+
+Recommended command order:
+1. `opendevbrowser_canvas` or `opendevbrowser canvas --command canvas.session.open` to get `canvasSessionId`, `leaseId`, `preflightState`, governance block states, and generation-plan requirements.
+2. Read the handshake before mutating. The handshake is the source of truth for:
+   - `governanceRequirements.requiredBeforeMutation`
+   - `governanceRequirements.requiredBeforeSave`
+   - `generationPlanRequirements.requiredBeforeMutation`
+   - `allowedLibraries`
+   - `mutationPolicy.allowedBeforePlan`
+   - treat `allowedLibraries.components`, `allowedLibraries.icons`, and `allowedLibraries.styling` as separate policy lanes:
+     `components` are reusable UI adapters such as `shadcn`,
+     `icons` are approved icon families,
+     `styling` is for utility/theme adapters such as `tailwindcss`
+3. Submit `canvas.plan.set` with all required non-empty objects:
+   - `targetOutcome`
+   - `visualDirection`
+   - `layoutStrategy`
+   - `contentStrategy`
+   - `componentStrategy`
+   - `motionPosture`
+   - `responsivePosture`
+   - `accessibilityPosture`
+   - `validationTargets`
+4. Only after the plan is accepted, call `canvas.document.patch`.
+5. Use `canvas.preview.render`, `canvas.tab.open`, `canvas.overlay.mount`, and `canvas.overlay.select` when a browser-backed live view is required.
+6. Use `canvas.feedback.poll` between mutation rounds and `canvas.document.save` or `canvas.document.export` to persist artifacts.
+
+Code-sync surface:
+- `canvas.session.attach` joins an existing canvas session as an `observer` or reclaims the write lease with `attachMode=lease_reclaim`.
+- `canvas.code.bind`, `canvas.code.unbind`, `canvas.code.pull`, `canvas.code.push`, `canvas.code.status`, and `canvas.code.resolve` manage TSX-first document bindings when a canvas file is round-tripped to repo code.
+
+Current `/canvas` parity notes:
+- All 26 public `canvas.*` commands are agent-callable through `opendevbrowser_canvas` and `opendevbrowser canvas --command ...`.
+- `canvas.feedback.subscribe` live streaming is public through the CLI only: use `--output-format stream-json` for the built-in polling bridge.
+- Tool-driven agents can achieve the same behavior by calling `canvas.feedback.subscribe` once and then looping on `canvas.feedback.poll` with the returned cursor.
+- `canvas.tab.sync` and `canvas.overlay.sync` are internal extension runtime helpers, not public commands.
+- `canvas_html` is still the default preview/export contract. `bound_app_runtime` is opt-in and only valid when runtime preflight and app-side instrumentation succeed.
+- Component and icon libraries currently render semantically, not package-faithfully. Treat `shadcn`, `tailwindcss`, `tabler`, `microsoft-fluent-ui-system-icons`, `3dicons`, and `@lobehub/fluent-emoji-3d` as metadata and constrained render lanes, not as general library import/export parity.
+- Annotation remains a separate surface today, but popup and canvas both ship per-item and combined `Copy` / `Send` actions. The remaining gap is that `Send` persists payloads for later `annotate --stored` retrieval instead of proactively injecting them into the active agent chat.
+
+Tailwind usage rule:
+- When `allowedLibraries.styling` includes `tailwindcss`, use it for layout, spacing, responsive, and state styling over canonical tokens/theme variables.
+- Do not treat Tailwind as a component inventory source or mix it into `componentStrategy.approvedLibraries`.
+- Preview/export should materialize a deterministic utility-class layer and stay self-contained; do not depend on a remote Tailwind CDN for canvas preview correctness.
+
+Failure handling:
+- `plan_required`: immediately call `canvas.plan.set`.
+- `revision_conflict`: reload with `canvas.document.load` and replay the patch batch against the latest revision.
+- `unsupported_target` or `restricted_url`: move the preview to a normal http(s) tab or fall back to managed mode.
+
+Operational references:
+- `artifacts/canvas-governance-playbook.md`
+- `assets/templates/canvas-handshake-example.json`
+- `assets/templates/canvas-generation-plan.v1.json`
+- `assets/templates/canvas-feedback-eval.json`
+- `assets/templates/canvas-blocker-checklist.json`
+
+## Diagnostics and Traceability
+
+Current diagnostics tools:
+- `opendevbrowser_console_poll`
+- `opendevbrowser_network_poll`
+- `opendevbrowser_debug_trace_snapshot` (combined page + console + network + exception channels)
+
+Reference: `artifacts/debug-trace-playbook.md`
+
+## Fingerprint Hardening
+
+Apply the minimum tier that meets reliability goals.
+
+- Tier 0: baseline deterministic automation.
+- Tier 1: coherence profile (default recommended).
+- Tier 2: runtime hardening.
+- Tier 3: adaptive managed hardening (optional).
+
+Reference: `artifacts/fingerprint-tiers.md`
+
+## Macro Guidance
+
+Use macros as normalized entrypoints for provider workflows.
+
+- Keep macro definitions declarative and typed.
+- Expand macros to canonical provider queries.
+- Emit provenance metadata (`macro`, `resolvedQuery`, `provider`).
+
+Reference: `artifacts/macro-workflows.md`

package/skills/opendevbrowser-best-practices/artifacts/browser-agent-known-issues-matrix.md

@@ -0,0 +1,44 @@
+# Browser Agent Known-Issues Matrix
+
+This matrix defines the minimum robustness controls for OpenDevBrowser workflow skills.
+
+## Issue Controls
+
+| ID | Known issue | Typical signals | Required controls | Evidence to capture |
+|---|---|---|---|---|
+| `ISSUE-01` | DOM churn invalidates refs | action fails after render, detached/stale element behavior, missing ref | enforce `snapshot -> one action -> snapshot`, retry once after fresh snapshot, avoid reusing refs across navigation | before/after snapshots + failing action + retry outcome |
+| `ISSUE-02` | Frame/iframe boundaries hide interactive targets | expected refs not found in top document, challenge widget rendered in iframe | detect frame context before action, route frame-specific steps, checkpoint when cross-origin challenge frame blocks continuation | snapshot outline showing frame branch + checkpoint note |
+| `ISSUE-03` | Popup/new-tab auth flows break linear scripts | click triggers new tab/popup, current tab loses focus | detect target/page changes, rebind to active auth target, verify post-auth return target | target/page list before and after auth click |
+| `ISSUE-04` | Step-up auth and session expiry alter login path | MFA/passkey prompt appears, unexpected redirect to reauth | branch login state machine explicitly, validate >=2 independent auth success signals, validate reauth policy separately | auth signal log with URL, element, network confirmation |
+| `ISSUE-05` | Anti-bot challenge loops stall automation | repeated challenge pages/widgets, repeated 403/429 around auth/submit | treat as checkpoint, never bypass, set loop budget, escalate after repeated challenge loops | challenge checkpoint log with timestamps and outcome |
+| `ISSUE-06` | Rate-limit pressure and server backoff ignored | 429 responses, throttle banners, `Retry-After` headers | stop aggressive retries, honor `Retry-After`, bounded retry budget with cooldown windows | network poll evidence with status + backoff decision |
+| `ISSUE-07` | MV3 extension service worker suspends state | extension relay disconnects after idle, handshake drop | re-check extension readiness before critical steps, include reconnect path and resumed snapshot checkpoint | daemon status (`extensionConnected`, `extensionHandshakeComplete`) before resume |
+| `ISSUE-08` | Restricted origins and policy blocks | `chrome://` / extension pages blocked, unsupported origin errors | validate URL/domain eligibility before workflow, fail fast with actionable reason | blocked-origin decision in run log |
+| `ISSUE-09` | Pagination drift and duplicate extraction | duplicate records across pages, endless loop/no page delta | canonical dedupe keys, terminal conditions, positive delta gate, checkpoint/resume metadata | pagination state + quality-gate report |
+| `ISSUE-10` | Locale/currency parsing inconsistency | mixed currency symbols, malformed numbers | normalize currency/amount explicitly, avoid cross-currency comparison without conversion context | normalized records with currency and parse confidence |
+| `ISSUE-11` | Discount anchor is weak or misleading | anchor price missing/untrusted, “sale” not below market | separate anchor discount from market discount, tag anchor confidence, require market-baseline confirmation | market analysis with anchor coverage and warnings |
+| `ISSUE-12` | Stale price or unsupported claims in presentation assets | captured price outdated, marketing claims not traceable | enforce freshness checks, claim-to-evidence mapping, block unsupported superlatives | claims-evidence map + pricing timestamp |
+
+## Skill Coverage Targets
+
+- `opendevbrowser-login-automation`: `ISSUE-01`, `ISSUE-02`, `ISSUE-03`, `ISSUE-04`, `ISSUE-05`, `ISSUE-06`, `ISSUE-07`
+- `opendevbrowser-form-testing`: `ISSUE-01`, `ISSUE-02`, `ISSUE-05`, `ISSUE-06`, `ISSUE-08`
+- `opendevbrowser-data-extraction`: `ISSUE-01`, `ISSUE-06`, `ISSUE-08`, `ISSUE-09`, `ISSUE-10`
+- `opendevbrowser-shopping`: `ISSUE-06`, `ISSUE-09`, `ISSUE-10`, `ISSUE-11`, `ISSUE-12`
+- `opendevbrowser-product-presentation-asset`: `ISSUE-10`, `ISSUE-11`, `ISSUE-12`
+- `opendevbrowser-research`: `ISSUE-06`, `ISSUE-09`, `ISSUE-10`, `ISSUE-12`
+
+## Source Notes
+
+- Playwright best practices (locator and timing stability): https://playwright.dev/docs/best-practices
+- Playwright frames guidance: https://playwright.dev/docs/frames
+- Playwright pages/popups guidance: https://playwright.dev/docs/pages
+- Chrome extension MV3 service worker lifecycle: https://developer.chrome.com/docs/extensions/develop/concepts/service-workers/lifecycle
+- HTTP 429 semantics and `Retry-After`: https://www.rfc-editor.org/rfc/rfc6585
+- OWASP Authentication Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html
+- WCAG 2.2 (accessible authentication): https://www.w3.org/TR/WCAG22/
+- Cloudflare Turnstile testing keys: https://developers.cloudflare.com/turnstile/tutorials/testing/
+- reCAPTCHA testing keys: https://developers.google.com/recaptcha/docs/faq
+- hCaptcha docs: https://docs.hcaptcha.com/
+- RFC 9309 robots protocol: https://www.rfc-editor.org/rfc/rfc9309
+- FTC deceptive pricing guide: https://www.ecfr.gov/current/title-16/chapter-I/subchapter-B/part-233

package/skills/opendevbrowser-best-practices/artifacts/canvas-governance-playbook.md

@@ -0,0 +1,141 @@
+# Canvas Governance Playbook
+
+## Purpose
+
+Use this playbook before any `/canvas` mutation and during every design-feedback loop. It keeps the runtime handshake, governance state, and evaluation rules aligned with the design-canvas spec.
+
+## Required command order
+
+1. `canvas.session.open`
+2. Read the handshake and confirm `preflightState: "handshake_read"`
+3. `canvas.plan.set`
+4. `canvas.plan.get` or `canvas.capabilities.get` until the runtime reports `plan_accepted`
+5. `canvas.document.patch`
+6. `canvas.preview.render` or `canvas.tab.open`
+7. `canvas.feedback.poll`
+8. `canvas.document.save` or `canvas.document.export`
+
+Mutation is blocked until the handshake has been read and the plan is accepted. A save is still invalid when required governance blocks remain missing in `requiredBeforeSave`.
+
+## Handshake requirements
+
+Every `canvas.session.open` response is the runtime contract. Read these fields before sending a patch:
+
+- `canvasSessionId`
+- `browserSessionId`
+- `documentId`
+- `leaseId`
+- `preflightState`
+- `governanceRequirements.requiredBeforeMutation`
+- `governanceRequirements.requiredBeforeSave`
+- `generationPlanRequirements.requiredBeforeMutation`
+- `allowedLibraries`
+- `allowedBeforePlan`
+
+Interpret `allowedLibraries` by lane:
+- `components` are reusable UI adapters such as `shadcn`
+- `icons` are approved icon families
+- `styling` is for utility/theme adapters such as `tailwindcss`
+- do not mix icon or styling libraries into `componentStrategy.approvedLibraries`
+
+Preflight states:
+- `handshake_read`
+- `plan_submitted`
+- `plan_accepted`
+- `patching_enabled`
+
+## Governance blocks
+
+The document must declare `designGovernance` with at least:
+
+- `intent`
+- `designLanguage`
+- `contentModel`
+- `layoutSystem`
+- `typographySystem`
+- `colorSystem`
+- `surfaceSystem`
+- `iconSystem`
+- `motionSystem`
+- `responsiveSystem`
+- `accessibilityPolicy`
+- `libraryPolicy`
+- `runtimeBudgets`
+
+The first accepted `generationPlan` must include:
+
+- `targetOutcome`
+- `visualDirection`
+- `layoutStrategy`
+- `contentStrategy`
+- `componentStrategy`
+- `motionPosture`
+- `responsivePosture`
+- `accessibilityPosture`
+- `validationTargets`
+
+## Blocker handling
+
+Canonical blocker path:
+
+```json
+{
+  "code": "plan_required",
+  "blockingCommand": "canvas.document.patch",
+  "requiredNextCommands": ["canvas.plan.set"],
+  "details": { "auditId": "CANVAS-01" }
+}
+```
+
+If `canvas.document.patch` or `canvas.document.save` returns a blocker, stop mutating and fix the missing handshake, governance, or plan requirement before retrying.
+
+## Canvas robustness issue classes
+
+| Audit ID | Failure class | Typical signal | Required response |
+|---|---|---|---|
+| `CANVAS-01` | Handshake missing or unread before mutation | `plan_required`, missing `handshake_read` evidence | Re-run `canvas.session.open` or `canvas.capabilities.get`, then `canvas.plan.set` |
+| `CANVAS-02` | Required governance block missing | save blocker, empty `requiredBeforeSave`, validation warning | Fill missing `designGovernance.*` fields before save/export |
+| `CANVAS-03` | Required `generationPlan` field missing or malformed | `canvas.plan.set` rejected or warnings retained | Submit a complete plan and wait for acceptance |
+| `CANVAS-04` | Library or icon-policy violation | validation warning, policy blocker, downgraded export | Adjust component/library choice to match `libraryPolicy` and `iconSystem` |
+| `CANVAS-05` | Unsupported target or overlay mount failure | `unsupported_target`, `restricted_url`, overlay mount error | Move to a normal http(s) preview target or managed mode |
+| `CANVAS-06` | Runtime budget exceeded or preview downgrade ignored | degrade warning, overflowed media/fonts/telemetry budget | Reduce preview cost or accept the downgrade before proceeding |
+| `CANVAS-07` | Feedback missing target attribution or validation metadata | feedback lacks `targetId`, `pageId`, `class`, or `evidenceRefs` | Re-poll or fix the feedback source before trusting the result |
+
+## Feedback evaluation loop
+
+Required categories:
+
+- `render`
+- `console`
+- `network`
+- `validation`
+- `performance`
+- `asset`
+- `export`
+
+Required fields per feedback item:
+
+- `documentId`
+- `pageId`
+- `prototypeId`
+- `targetId`
+- `documentRevision`
+- `severity`
+- `class`
+- `message`
+- `evidenceRefs`
+
+Streaming checks:
+
+- `feedback.item` carries the canonical feedback payload
+- `feedback.heartbeat` proves the subscription is still alive
+- `feedback.complete` explains why the stream ended
+
+## Router and template references
+
+- `scripts/odb-workflow.sh canvas-preflight`
+- `scripts/odb-workflow.sh canvas-feedback-eval`
+- `assets/templates/canvas-handshake-example.json`
+- `assets/templates/canvas-generation-plan.v1.json`
+- `assets/templates/canvas-feedback-eval.json`
+- `assets/templates/canvas-blocker-checklist.json`