fix: harden shopping and workflow readiness gates

docs/CLI.md

@@ -518,7 +518,7 @@ Notes:
 - Raw audit surfaces stay separate: `offers.json` preserves structured offers, `comparison.csv` preserves the tabular comparison with appended currency and total-status audit fields, `meta.json` preserves workflow diagnostics, and `deals-context.json` preserves `query`, report-derived `highlights`, raw `offers`, and `meta` for agent handoff.
 - `compact` and `context` modes summarize the same report guidance as `deals.md`; `json` mode still returns raw offers and meta.
 - Expect warnings for stale, inferred, or missing price freshness; unknown or out-of-stock availability; weak query relevance; suspicious titles; duplicate same-title or same-product pressure; workflow alerts; and advisory region handling.
-- Treat `--region` as advisory unless `meta.selection.region_authoritative=true`. If `meta.alerts` includes `reasonCode=region_unenforced`, do not present the output as a trustworthy regional comparison.
+- Treat `--region` as advisory unless `meta.selection.region_authoritative=true`. If `meta.alerts` includes `reasonCode=region_unenforced`, do not present the output as a trustworthy regional comparison. The alert is emitted only for selected provider diagnostics that did not enforce the requested region; enforced-region diagnostics do not create that warning.
 - The Market Baseline section is computed only from deterministic same-currency evidence. If sample size or currency coverage is insufficient, the report says `market baseline unavailable` instead of inventing savings.
 - Seller trust, return policy, warranty, condition, shipping certainty, and price history are not guaranteed fields. Treat them as unavailable unless the raw offer attributes and report text explicitly include them.
 - When a run returns no final offers, inspect `meta.primaryConstraintSummary` first.
@@ -618,7 +618,7 @@ Notes:
 - Workflow outputs can include typed `nextStepGuidance` with `readiness`, `reasonCode`, `primaryAction`, command examples, `paramsExamples`, `validationChecks`, `fallbackPolicy`, and `doNotProceedIf` blockers.
 - Harvest outputs separate operational completion, guidance readiness, and product readiness. `success:true` or `ok:true` means the command completed and wrote artifacts; top-level `ready` is product-ready only when `productSuccess=true`, `artifactAuthority=product_ready`, and `evidenceAuthority` is non-diagnostic. `readiness` and `guidanceReadiness` expose the next-step guidance state.
 - Treat product readiness as the gate between artifact completion and design readiness. Continue to Canvas only when top-level `ready=true`, `productSuccess=true`, `artifactAuthority=product_ready`, ranked references are non-empty, manifest-backed authority evidence exists, and no `doNotProceedIf` condition applies. For canonical Pinterest pin-media harvests, Canvas continuation requires `evidenceAuthority=pin_media_ready` and manifest-backed `pin-media-index.json`; `snapshot_ready` and `motion_ready` are not substitutes for pin-media readiness.
-- Pinterest product readiness is pin-media-first: canonical pin URLs become product-ready only when their first-party pin-media artifact is captured, persisted, present in its manifest-backed index, and free of blocking warnings. Screenshot and screencast artifacts can inform diagnostics or motion design, but they do not satisfy required Pinterest pin-media readiness. The exact `login_or_challenge_state` and strict byte-backed `interface_chrome_shell` diagnostics are non-blocking only for trusted first-party manifest-backed pin-media bytes; broader login, challenge, captcha, search-shell, promoted, ad, blank, tiny, or chrome-only blockers still demote readiness unless query-discovered canonical pins also produce complete pin-media authority. Screenshot failure after pin-media success is a non-blocking caveat when pin-media authority is complete. `pin-media-index.json` remains Pinterest authority, `media-analysis.json` remains advisory, and `motion-evidence.json` remains browser replay authority. Multimodal agents reason over those artifacts directly.
+- Pinterest product readiness is pin-media-first: canonical pin URLs become product-ready only when their first-party pin-media artifact is captured, persisted, present in its manifest-backed index, and free of blocking warnings. Screenshot and screencast artifacts can inform diagnostics or motion design, but they do not satisfy required Pinterest pin-media readiness. The exact `login_or_challenge_state` and strict byte-backed `interface_chrome_shell` diagnostics are non-blocking only for trusted first-party manifest-backed pin-media bytes; broader login, challenge, captcha, search-shell, promoted, ad, blank, tiny, or chrome-only blockers still demote readiness unless query-discovered canonical pins also produce complete pin-media authority. When pin-media authority is complete, unavailable supplemental viewport screenshot evidence is recorded as skipped and satisfied by pin media, not as product-readiness failure. `pin-media-index.json` remains Pinterest authority, `media-analysis.json` remains advisory, and `motion-evidence.json` remains browser replay authority. Multimodal agents reason over those artifacts directly.
 - CLI completion text includes `guidanceReadiness=<value> productSuccess=false artifactAuthority=<value> evidenceAuthority=<value>` when guidance readiness exists but product readiness is false. Product-ready runs can still emit `readiness=<value>`.
 - For `needs_recovery`, `blocked`, or `diagnostic_only`, follow the primary recovery action first. Common blockers are zero references, empty ranked references, failed required screenshot, screencast, or pin-media evidence, provider unavailability, login or challenge screens, and diagnostic-only captures.
 - The ready follow-through path is explicit: read `advanced-brief.md`, `meta-prompt.md`, `evidence.json`, `ranked-references.json`, `bundle-manifest.json`, `media-analysis.json` when present, and screenshot, screencast, or pin-media evidence first; load `opendevbrowser_skill_load opendevbrowser-best-practices "quick start"`, `opendevbrowser_skill_load opendevbrowser-design-agent "canvas-contract"`, and `opendevbrowser_skill_load opendevbrowser-motion-design "quick start"`; continue only if `canvas-plan.request.json` exists; open a Canvas session; fill the session ids in `canvas-plan.request.json`; run `opendevbrowser canvas --command canvas.plan.set --params-file ./canvas-plan.request.json`; confirm `planStatus=accepted`; then patch only the governance blocks called out by `design-agent-handoff.json`.

docs/SURFACE_REFERENCE.md

@@ -578,6 +578,7 @@ Auth and policy:
 - Workflow and macro execute browser options: `research run`, `shopping run`, `product-video run`, `inspiredesign run`, `inspiredesign harvest`, and `macro-resolve --execute` accept `--browser-mode auto|extension|managed`; `extension` reuses relay-backed browser state, while `managed` runs a deterministic managed browser. Workflow `--profile <name>` selects a named managed profile for provider browser fallback; registry-backed explicit CDP profiles use `cdp-profile start` plus `connect --profile` for browser/session primitives until workflows expose an explicit-CDP transport selector.
 - Workflow and macro execute cookie options: `research run`, `shopping run`, `product-video run`, `inspiredesign run`, `inspiredesign harvest`, and `macro-resolve --execute` accept `--use-cookies` and `--cookie-policy-override off|auto|required` (`--cookie-policy` alias) so provider macros can require observable cookie-backed browser sessions.
 - Workflow and macro execute override flags: `research run`, `shopping run`, `product-video run`, `inspiredesign run`, `inspiredesign harvest`, and `macro-resolve --execute` accept `--challenge-automation-mode off|browser|browser_with_helper`, which maps to `challengeAutomationMode` with `run > session > config` precedence.
+- Shopping `--region` remains advisory unless workflow output reports `region_authoritative=true`. The `region_unenforced` alert is emitted only for selected provider diagnostics that did not enforce the requested region; enforced-region diagnostics do not create that warning.
 - Inspiredesign harvest flags: `--query`, repeatable `--provider`, `--max-references 1..10`, and `--visual-evidence off|auto|required`. Harvest requires `--query` or at least one `--url`, keeps the daemon method as `inspiredesign.run`, defaults to `mode=path`, `visualEvidence=required`, and `maxReferences=5`, and keeps explicit `--url` references before discovered references.
 - Before trusting daemon-backed `inspiredesign harvest` results, run `npx opendevbrowser status --daemon --output-format json` and require `data.fingerprintCurrent === true`; restart or isolate the daemon when it is false or missing.
 - Inspiredesign harvest supports browser-native site recipes for visually driven sites. `--provider social/pinterest` selects the Pinterest recipe and should use a dedicated managed headed profile with cookies and `--cookie-policy required` for non-Google logged-in search; use extension `/ops` when live active-tab reuse is required. Registry-backed explicit CDP profiles are available for browser/session primitives, but provider workflows do not yet expose an explicit-CDP transport selector. Query-based Pinterest harvests become product-ready only through query-discovered canonical `/pin/{id}/` references plus manifest-backed first-party pin-media bytes; login/challenge and search-shell diagnostics are recovery paths, not product-ready evidence. Compatible Pinterest URL recovery can run as `--provider social/pinterest --url <pinterest-url>` without `--query`; use one canonical `/pin/{id}/` URL per harvest when validating design-ready pin media. Generic provider plus URL recovery without query remains rejected. Pinterest is not registered as a default full social provider.
@@ -595,7 +596,7 @@ Auth and policy:
 - Workflow response keys: artifact-bearing workflow success payloads use `artifact_path`; provider follow-up summaries use `meta.primaryConstraintSummary`; typed recovery and handoff payloads use `nextStepGuidance.readiness`, `reasonCode`, `primaryAction`, `paramsExamples`, `validationChecks`, `fallbackPolicy`, and `doNotProceedIf` when available. Inspiredesign harvest also reports product `ready`, `guidanceReady`, `guidanceReadiness`, `productSuccess`, `harvestReadiness`, `readiness`, `rankedReferenceCount`, `evidenceAuthority`, and `artifactAuthority` so wrapper success is not confused with design readiness. Product `ready` is true only when authority gates pass.
 - `design-contract.json.colorSystem.tokens` and `implementation-plan.json.tokenStrategy.colors` use explicit `{ light, dark }` semantic token maps. `design-agent-handoff.json.implementationContext.tokenStrategy` carries the same dual-mode token strategy for implementation agents.
 - Continue to Canvas only when top-level `ready=true`, `productSuccess=true`, `artifactAuthority=product_ready`, ranked references are non-empty, no matching `doNotProceedIf` blockers remain active, and manifest-backed authority evidence exists. Strict proof reviews should inspect `evidence.json`, `ranked-references.json`, `pin-media-index.json`, `motion-evidence.json`, `media-analysis.json`, and `bundle-manifest.json` directly before accepting release or Canvas follow-through evidence. For canonical Pinterest pin-media harvests, Canvas continuation requires `evidenceAuthority=pin_media_ready` and manifest-backed `pin-media-index.json`; `snapshot_ready` and `motion_ready` are not substitutes for pin-media readiness. For `needs_recovery`, `blocked`, or `diagnostic_only`, follow recovery-first guidance and do not treat emitted artifacts as design-ready.
-- Pinterest product readiness is pin-media-first: canonical pin URLs become product-ready only when their first-party pin-media artifact is captured, persisted, present in its manifest-backed index, and free of blocking warnings. `pin-media-index.json` remains the only pin-media readiness and provenance authority for persisted first-party bytes. Screenshot and screencast artifacts can inform diagnostics or motion design, but they do not satisfy required Pinterest pin-media readiness. The exact `login_or_challenge_state` and strict byte-backed `interface_chrome_shell` diagnostics are non-blocking only for trusted first-party manifest-backed pin-media bytes; broader login, challenge, captcha, search-shell, promoted, ad, blank, tiny, or chrome-only blockers still demote readiness unless query-discovered canonical pins also produce complete pin-media authority. Screenshot failure after pin-media success is a non-blocking caveat when pin-media authority is complete. `media-analysis.json` remains advisory, and `motion-evidence.json` remains browser replay authority.
+- Pinterest product readiness is pin-media-first: canonical pin URLs become product-ready only when their first-party pin-media artifact is captured, persisted, present in its manifest-backed index, and free of blocking warnings. `pin-media-index.json` remains the only pin-media readiness and provenance authority for persisted first-party bytes. Screenshot and screencast artifacts can inform diagnostics or motion design, but they do not satisfy required Pinterest pin-media readiness. The exact `login_or_challenge_state` and strict byte-backed `interface_chrome_shell` diagnostics are non-blocking only for trusted first-party manifest-backed pin-media bytes; broader login, challenge, captcha, search-shell, promoted, ad, blank, tiny, or chrome-only blockers still demote readiness unless query-discovered canonical pins also produce complete pin-media authority. When pin-media authority is complete, unavailable supplemental viewport screenshot evidence is recorded as skipped and satisfied by pin media, not as product-readiness failure. `media-analysis.json` remains advisory, and `motion-evidence.json` remains browser replay authority.
 - Routine workflow bundles should omit output roots and inspect the returned `artifact_path` first. When output roots are omitted, persisted bundles use `.opendevbrowser/<namespace>/<runId>` and include `bundle-manifest.json`. CLI invocations resolve omitted roots from cwd before daemon dispatch; direct daemon RPC uses `core.workspaceRoot/.opendevbrowser`; direct OpenCode workflow tools use `deps.workspaceRoot/.opendevbrowser`. If a wrapper must pass an explicit workflow root, prefer `.opendevbrowser`; explicit external output roots remain caller-controlled for intentional temp, release, debug, audit, screenshot, and screencast lanes.
 - `artifacts cleanup --expired-only` without `--output-dir` targets the current working directory's `.opendevbrowser` root. Use `--output-dir /tmp/opendevbrowser` only when intentionally cleaning an explicit temp artifact root.
 - Browser evidence omitted outputs use workspace-local artifact roots: screenshots write `.opendevbrowser/screenshot/<uuid>/capture.png` with `path` and `artifact_path`, and screencasts write `.opendevbrowser/screencast/<uuid>` with replay files. Explicit `--path` and `--output-dir` remain caller-controlled. Browser screenshot, screencast, Canvas, annotation, desktop audit, and release proof outputs are intentional non-bundle lanes, do not promise `bundle-manifest.json`, and are not targets for bundle manifest cleanup.