Document Workspace V2 Playwright gate for repeatable local validation - PR_11_321

Author: DavidQ

docs/dev/codex_commands.md

@@ -222,3 +222,10 @@ PR_11_320
 ```bash
 npx @openai/codex run --model gpt-5.3-codex --reasoning medium "Implement PR_11_320: Update Workspace V2 Playwright gate to execute installed Playwright command path only, preserving fail-fast and summary output."
 ```
+
+---
+PR_11_321
+
+```bash
+npx @openai/codex run --model gpt-5.3-codex --reasoning medium "Implement PR_11_321: Document the Workspace V2 Playwright validation gate for repeatable local testing."
+```

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Update Workspace V2 Playwright gate to use installed command path while preserving fail-fast summary behavior - PR 11.320
+Document Workspace V2 Playwright validation gate usage and expected output/exit behavior - PR 11.321

docs/dev/reports/PR_11_321_report.md

@@ -0,0 +1,24 @@
+# PR_11_321 Report
+
+## Scope
+- docs-only update for Workspace V2 Playwright validation gate documentation.
+
+## Files Changed
+- `docs/dev/workspace_v2_playwright_gate.md`
+- `docs/pr/PR_11_321_WORKSPACE_V2_PLAYWRIGHT_GATE_DOCUMENTATION/PLAN_PR.md`
+- `docs/pr/PR_11_321_WORKSPACE_V2_PLAYWRIGHT_GATE_DOCUMENTATION/BUILD_PR.md`
+- `docs/dev/codex_commands.md`
+- `docs/dev/commit_comment.txt`
+
+## Validation Run
+- `rg -n "npm run test:workspace-v2" docs/dev/workspace_v2_playwright_gate.md`
+- `rg -n "tests/results" docs/dev/workspace_v2_playwright_gate.md`
+- `rg -n "non-zero exit code|non-zero exit" docs/dev/workspace_v2_playwright_gate.md`
+
+## Validation Results
+- PASS: docs mention `npm run test:workspace-v2`.
+- PASS: docs mention `tests/results` output path.
+- PASS: docs mention non-zero exit behavior on failure.
+
+## Full Samples Smoke
+- Skipped intentionally because this PR is docs-only and does not modify runtime, shared framework, or sample execution logic.

docs/dev/workspace_v2_playwright_gate.md

@@ -0,0 +1,30 @@
+# Workspace V2 Playwright Validation Gate
+
+Use this gate for repeatable local validation of Workspace V2 UI behavior.
+
+## Command
+- `npm run test:workspace-v2`
+
+## What It Runs
+- Executes the installed Playwright UI regression command for Workspace V2.
+- Fails fast and returns a non-zero exit code on any test failure.
+
+## Output Paths
+- Test artifacts are written under `tests/results/`.
+- Trace artifacts are written under `tests/results/**` (for example in artifacts folders).
+- HTML report is written under `tests/results/report`.
+- Reporter auto-open behavior is controlled by `playwright.config.cjs`.
+
+## Pass/Fail Behavior
+- Success:
+  - tests complete
+  - summary shows pass count
+  - exit code is `0`
+- Failure:
+  - any failed test causes non-zero exit
+  - summary includes failed count
+  - CI/local gate should treat this as a hard failure
+
+## Smoke Test Policy
+- For Workspace V2 gate-only PRs, full samples smoke test should be skipped.
+- Run full samples smoke only when shared sample framework/runtime is changed.

docs/pr/PR_11_321_WORKSPACE_V2_PLAYWRIGHT_GATE_DOCUMENTATION/BUILD_PR.md

@@ -0,0 +1,16 @@
+# BUILD_PR_11_321
+
+## Implementation
+- Added `docs/dev/workspace_v2_playwright_gate.md` with concise gate documentation for:
+  - `npm run test:workspace-v2`
+  - artifact output path `tests/results/` and `tests/results/**`
+  - HTML report behavior at `tests/results/report`
+  - expected gate pass/fail behavior, including non-zero exit on failure
+  - full samples smoke skip guidance for gate-only PRs
+- Updated `docs/dev/codex_commands.md` with PR_11_321 command entry.
+- Updated `docs/dev/commit_comment.txt` with PR_11_321 commit comment text.
+
+## Validation
+- `rg -n "npm run test:workspace-v2" docs/dev/workspace_v2_playwright_gate.md`
+- `rg -n "tests/results" docs/dev/workspace_v2_playwright_gate.md`
+- `rg -n "non-zero exit code|non-zero exit" docs/dev/workspace_v2_playwright_gate.md`

docs/pr/PR_11_321_WORKSPACE_V2_PLAYWRIGHT_GATE_DOCUMENTATION/PLAN_PR.md

@@ -0,0 +1,18 @@
+# PLAN_PR_11_321
+
+## Purpose
+Document the Workspace V2 Playwright validation gate for repeatable local testing.
+
+## Scope
+- `docs/dev/workspace_v2_playwright_gate.md`
+- `docs/dev/codex_commands.md`
+- `docs/dev/commit_comment.txt`
+- `docs/dev/reports/PR_11_321_report.md`
+
+## Steps
+1. Add a concise Workspace V2 Playwright gate usage note in `docs/dev`.
+2. Include command, output paths, HTML report behavior, and expected pass/fail exit behavior.
+3. Document when full samples smoke should be skipped.
+4. Add PR_11_321 execution entry in `docs/dev/codex_commands.md`.
+5. Update `docs/dev/commit_comment.txt` with the PR_11_321 commit summary line.
+6. Run targeted docs mention validation for required strings.