prizmkit 1.1.70 → 1.1.74

package/bundled/dev-pipeline-windows/templates/bugfix-bootstrap-prompt.md

@@ -48,7 +48,7 @@ You are the **bug fix session agent**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}".
 1. **context-snapshot.md is your single source of truth** — After it is built, read context-snapshot.md instead of re-reading individual source files.
 2. **Never re-read your own writes** — Trust your write was correct.
 3. **Stay focused** — Do NOT explore code unrelated to this bug.
-4. **Minimize tool output** — Capture to temp file, scan head/tail, filter with Select-String/PowerShell object filtering. Never load full output.
+4. **Minimize tool output** — Capture to temp file, scan first/last lines, filter with Select-String, regex matching, or PowerShell object filtering. Never load full output.
 5. **No intermediate commits** — All changes committed once at the end via `/prizmkit-committer`.
 
 ## Bug Fix Artifacts Directory
@@ -195,7 +195,7 @@ Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/`:
 **Gate Check — Review Report**:
 After `/prizmkit-code-review` returns, verify the review report:
 ```powershell
-if (Select-String -Path .prizmkit/bugfix/{{BUG_ID}}/review-report.md -Pattern "## Verdict" -Quiet) { "GATE:PASS" } else { "GATE:MISSING" }
+if (Select-String -Path .prizmkit/bugfix/{{BUG_ID}}/review-report.md -Pattern "## Verdict" -Quiet -ErrorAction SilentlyContinue) { "GATE:PASS" } else { "GATE:MISSING" }
 ```
 If GATE:MISSING:
 - Do not re-run `/prizmkit-code-review` in an unbounded report-repair loop.

package/bundled/dev-pipeline-windows/templates/feature-list-schema.json

@@ -163,7 +163,7 @@
             "items": {
               "type": "string"
             },
-            "description": "AI-generated summary of key changes from this feature session. Useful to provide rich dependency context to downstream features. Each item is a concise statement about what was built/changed (e.g. APIs added, models created, key file paths)."
+            "description": "AI-generated summary of key changes from this feature session. Used to provide rich dependency context to downstream features. Each item is a concise statement about what was built/changed (e.g. APIs added, models created, key file paths)."
           },
           "user_context": {
             "type": "array",

package/bundled/dev-pipeline-windows/templates/refactor-bootstrap-prompt.md

@@ -219,7 +219,7 @@ Evidence must cover affected UI render, primary user interactions, behavior-sens
 - **Gate Check — Review Report**:
   After Reviewer returns, verify the review report contains a verdict:
   ```powershell
-  if (Select-String -Path .prizmkit/refactor/{{REFACTOR_ID}}/review-report.md -Pattern "## Verdict" -Quiet) { "GATE:PASS" } else { "GATE:MISSING" }
+  if (Select-String -Path .prizmkit/refactor/{{REFACTOR_ID}}/review-report.md -Pattern "## Verdict" -Quiet -ErrorAction SilentlyContinue) { "GATE:PASS" } else { "GATE:MISSING" }
   ```
   If GATE:MISSING:
   - Do not enter an unbounded report-repair loop and do not repeatedly re-spawn Reviewer.

package/bundled/dev-pipeline-windows/templates/refactor-list-schema.json

@@ -182,7 +182,7 @@
             "items": {
               "type": "string"
             },
-            "description": "AI-generated summary of key changes from this refactor session. Useful to provide rich dependency context to downstream refactors. Each item is a concise statement about what was refactored (e.g. modules extracted, files restructured, interfaces changed)."
+            "description": "AI-generated summary of key changes from this refactor session. Used to provide rich dependency context to downstream refactors. Each item is a concise statement about what was refactored (e.g. modules extracted, files restructured, interfaces changed)."
           },
           "user_context": {
             "type": "array",

package/bundled/dev-pipeline-windows/templates/sections/context-budget-rules.md

@@ -8,16 +8,16 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 2. **Never re-read your own writes** — After you create/modify a file, do NOT read it back to verify. Trust your write was correct.
 3. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
 4. **One task at a time** — Complete and test one task before starting the next.
-5. **Minimize tool output** — Never load full command output into context. First capture to a temp file (`cmd 2>&1 | Tee-Object (Join-Path $env:TEMP "out.txt") | Select-Object -Last 20`), then scan the head/tail to identify relevant fields, and use targeted filtering (`Select-String`, `filtering`, `PowerShell object filtering`) to extract only the information needed for the current task. Only read the filtered result — never the raw full output.
+5. **Minimize tool output** — Never load full command output into context. First capture to a temp file (`& { <command> } 2>&1 | Tee-Object (Join-Path $env:TEMP "out.txt") | Select-Object -Last 20`), then scan the first/last lines to identify relevant fields, and use targeted filtering (`Select-String`, regex matching, PowerShell object filtering) to extract only the information needed for the current task. Only read the filtered result — never the raw full output.
 6. **No intermediate commits** — Do NOT run `git add`/`git commit` during implementation phases. All changes are committed once at the end via `/prizmkit-committer`.
-7. **Capture test output once** — When running test suites, always use `& { {{TEST_CMD}} } 2>&1 | Tee-Object (Join-Path $env:TEMP "test-out.txt") | Select-Object -Last 20`. Then Select-String (Join-Path $env:TEMP "test-out.txt") for details. Never re-run the suite just to apply a different filter.
+7. **Capture test output once** — When running test suites, always use `& { {{TEST_CMD}} } 2>&1 | Tee-Object (Join-Path $env:TEMP "test-out.txt") | Select-Object -Last 20`. Then Select-String `(Join-Path $env:TEMP "test-out.txt")` for details. Never re-run the suite just to apply a different filter.
 8. **Scaffold / generated file awareness (CRITICAL)** — When you run a scaffolding tool or package manager init command (`npm init`, `npx create-*`, `vite create`, `cargo init`, `go mod init`, `rails new`, `django-admin startproject`, `npx shadcn-ui init`, etc.), the output files are **generated boilerplate**. You MUST:
    - Identify and mentally tag all files created by the tool as "scaffold files"
    - Record the list of scaffold-generated files in context-snapshot.md under a `### Scaffold Files (do not re-read)` section
    - **NEVER re-read scaffold files** after initial creation. Their content is standard boilerplate — you already know what they contain from the tool that generated them
    - If you need to modify a scaffold file, make the edit directly without reading it first (you know the standard template content)
    - This applies equally to `node_modules/`, `package-lock.json`, generated config files (`tsconfig.json`, `vite.config.ts`, `tailwind.config.js`, `.eslintrc`, etc.) produced by init commands
-   - When passing context to subagents, explicitly tell them the scaffold-generated files so they skip reading them too
+   - When passing context to subagents, explicitly tell them Get-Command files are scaffold-generated so they skip reading them too
 9. **Package version verification (HARD CONSTRAINT — BLOCKING)** — Before writing ANY dependency version in `package.json`, `requirements.txt`, `Cargo.toml`, `go.mod`, `Gemfile`, `pyproject.toml`, or any other dependency manifest:
    - You MUST verify the real version exists by querying the package registry first:
      - npm/Node.js: `npm view <package> dist-tags.latest 2>$null`

package/bundled/dev-pipeline-windows/templates/sections/failure-capture.md

@@ -5,7 +5,7 @@ If you encounter an unrecoverable error, context overflow, or are about to exit
 1. Write `.prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md` BEFORE exiting:
    ```
    FAILURE_TYPE: timeout | test_failure | review_rejected | context_overflow | unknown
-   PHASE: <failed phase>
+   PHASE: <Get-Command phase failed>
    ROOT_CAUSE: <1-2 sentence explanation>
    ATTEMPTED: <approaches already tried>
    SUGGESTION: <what the next session should try differently>

package/bundled/dev-pipeline-windows/templates/sections/feature-context.md

@@ -4,33 +4,18 @@
 Use this material according to the following priority:
 
 1. **Task Contract** — defines current scope and Verification Gates.
-2. **User Raw Context** — authoritative constraints, but not automatic scope expansion.
-3. **Completed Dependencies** — existing behavior and interfaces; do not re-implement them.
-4. **Project Brief** — product background and architecture alignment.
-5. **App Global Context** — stack, runtime, and testing conventions.
-6. **Project Conventions** — repository-specific rules.
-
-### User Raw Context
-
-{{USER_CONTEXT}}
+2. **Completed Dependencies** — existing interfaces; do not re-implement.
+3. **App Global Context** — stack, runtime, testing conventions.
 
 ### Completed Dependencies
 
-> Use this section to understand available interfaces and avoid duplicating completed work.
-
 {{COMPLETED_DEPENDENCIES}}
 
-### Project Brief
-
-> Use this section for alignment only. Do not treat unrelated backlog items as current feature scope.
-
-{{PROJECT_BRIEF}}
-
 ### App Global Context
 
 {{GLOBAL_CONTEXT}}
 
 ### Project Conventions
 
-> Read {{PLATFORM_CONVENTIONS}} for project-level coding standards, architecture decisions, and development rules. Follow these conventions throughout implementation.
+> Read {{PLATFORM_CONVENTIONS}} for project-level coding standards and architecture decisions.
 </feature-context>

package/bundled/dev-pipeline-windows/templates/sections/phase-browser-verification-auto.md

@@ -1,84 +1,283 @@
-### Browser Verification — MANDATORY
+### Browser Verification (Auto-Select Tool) — MANDATORY
 
-You MUST attempt this phase. Mark it as skipped only when no usable browser tool can be found, installed, or started. Use native PowerShell commands for setup, server lifecycle, and cleanup.
+You MUST execute this phase. Do NOT skip it. Select the best available browser tool at runtime and use PowerShell-native commands for setup, server lifecycle, and cleanup.
 
-**Step 0 — Tool Selection (BLOCKING — decide before any browser action)**:
+**Tool Selection**: Choose the best browser tool at runtime.
 
+**Step 0 — Detect available tools**:
 ```powershell
+"=== playwright-cli ==="
 $playwright = Get-Command playwright-cli -ErrorAction SilentlyContinue
+if ($playwright) { playwright-cli --version } else { "NOT_INSTALLED" }
+"=== opencli ==="
 $opencli = Get-Command opencli -ErrorAction SilentlyContinue
-if ($playwright) { playwright-cli --version } else { "PLAYWRIGHT_CLI:NOT_INSTALLED" }
-if ($opencli) { opencli --version } else { "OPENCLI:NOT_INSTALLED" }
+if ($opencli) { opencli --version } else { "NOT_INSTALLED" }
+if ($opencli) {
+  opencli doctor 2>$null
+  if ($LASTEXITCODE -ne 0) { "OPENCLI_BRIDGE_FAILED" }
+}
 ```
 
-Use this single decision tree:
-1. If `playwright-cli` is available, use it by default for local dev-server verification.
-2. Else if `opencli` is available, run `opencli doctor`; use `opencli` only if doctor passes.
-3. Else install `playwright-cli` as the default:
+**Decision table**:
+| Condition | Tool |
+|-----------|------|
+| Only playwright-cli available | playwright-cli |
+| Only opencli available (doctor passes) | opencli |
+| Both — local dev server, forms, components | playwright-cli |
+| Both — needs real login state (OAuth/SSO) | opencli |
+| Both — third-party integration verification | opencli |
+| Neither available | Install playwright-cli as default |
+
+Then follow the corresponding tool's workflow above (Steps 1-3).
+
+If you choose playwright-cli, follow this workflow:
+
+**Using: playwright-cli**
+
+**CRITICAL CONSTRAINT — playwright-cli ONLY, NO Playwright MCP**:
+- You MUST use `playwright-cli` (the CLI tool) for ALL browser interactions in this phase
+- **NEVER** use Playwright MCP server, Playwright MCP tools, or any MCP-based browser automation
+- If you have Playwright MCP configured, IGNORE it entirely — use the CLI command `playwright-cli` exclusively
+- All browser actions go through `playwright-cli <command>` in the PowerShell tool, not through any MCP tool call
+
+**Step 0 — Playwright CLI Readiness Check (BLOCKING — must pass before any browser action)**:
+
+0a. Check if `playwright-cli` is installed:
+```powershell
+$playwright = Get-Command playwright-cli -ErrorAction SilentlyContinue
+if ($playwright) { playwright-cli --version } else { "NOT_INSTALLED" }
+```
+If output is `NOT_INSTALLED`, install it:
+```powershell
+npm install -g @playwright/cli@latest
+```
+Then verify installation succeeded:
+```powershell
+playwright-cli --version
+```
+If installation fails, log the error in context-snapshot.md under `## Browser Verification: SKIPPED — playwright-cli installation failed` and proceed to the next phase. Do NOT attempt browser verification without playwright-cli.
+
+0b. Learn playwright-cli usage (run once per session to understand available commands):
+```powershell
+playwright-cli --help
+```
+Use this output to determine the correct commands for your verification steps. Do NOT guess command syntax — refer to the help output.
+
+0c. Check if playwright-cli skill is installed for the current AI platform:
+```powershell
+$currentPlatform = "unknown"
+$skillDir = $null
+if (Get-Command claude -ErrorAction SilentlyContinue) {
+  $currentPlatform = "claude"
+  $skillDir = Join-Path $HOME ".claude\skills"
+} elseif (Get-Command cbc -ErrorAction SilentlyContinue) {
+  $currentPlatform = "codebuddy"
+  $skillDir = Join-Path $HOME ".cbc\skills"
+}
+
+$skillExists = $false
+if ($skillDir) {
+  $directSkill = Join-Path $skillDir "playwright-cli"
+  $matchingSkills = Get-ChildItem -Path $skillDir -Filter "playwright*" -ErrorAction SilentlyContinue
+  $skillExists = (Test-Path -LiteralPath $directSkill) -or [bool]$matchingSkills
+}
+if ($skillExists) { "SKILL_EXISTS" } else { "SKILL_MISSING" }
+```
+If `SKILL_MISSING`:
+```powershell
+playwright-cli install --skills
+```
+If the current platform is NOT claude, move the installed skill files to the correct location:
+```powershell
+$claudeSkillDir = Join-Path $HOME ".claude\skills"
+$sourceSkill = Join-Path $claudeSkillDir "playwright-cli"
+if ($currentPlatform -ne "claude" -and $currentPlatform -ne "unknown" -and $skillDir -and (Test-Path -LiteralPath $sourceSkill)) {
+  New-Item -ItemType Directory -Force -Path $skillDir | Out-Null
+  Copy-Item -Recurse -Force -Path $sourceSkill -Destination $skillDir
+  "Moved playwright-cli skill from claude to $currentPlatform"
+}
+```
+
+0d. Read the installed playwright-cli skill for workflow guidance:
+After skill installation, read the skill's SKILL.md to understand recommended workflows and patterns. Use these patterns to construct your verification flow — do NOT invent your own patterns if the skill provides them.
+
+**Step 1 — Start Dev Server**:
+
+You know this project's tech stack. Detect and start the dev server yourself:
+
+1. Identify the dev server start command from project config (`package.json` scripts, `Makefile`, `docker-compose.yml`, etc.)
+2. **Detect the dev server port** — use the pre-detected port from pipeline if available, otherwise extract from project config. Do NOT hardcode or guess the port:
+   ```powershell
+   $DEV_PORT = "{{DEV_PORT}}"
+   if ($DEV_PORT -eq "{{DEV_PORT}}" -or [string]::IsNullOrWhiteSpace($DEV_PORT)) {
+     $detectedPort = ""
+     if (Test-Path -LiteralPath "package.json") {
+       $detectedPort = node -e "const p=require('./package.json'); const s=(p.scripts?.dev) || ''; const m=s.match(/-p\s+(\d+)/); console.log(m?m[1]:'')"
+     }
+     if (-not $detectedPort -and $env:NEXT_PUBLIC_SITE_URL -match ':([0-9]+)') {
+       $detectedPort = $Matches[1]
+     }
+     if ($detectedPort) { $DEV_PORT = $detectedPort } else { $DEV_PORT = "3000" }
+   }
+   "Detected DEV_PORT=$DEV_PORT"
+   ```
+3. Verify the port is available and start the dev server in the background, capturing its process id:
+   ```powershell
+   $portBusy = Get-NetTCPConnection -LocalPort ([int]$DEV_PORT) -ErrorAction SilentlyContinue
+   if ($portBusy) { "PORT_IN_USE" } else { "PORT_FREE" }
+   $devServerCommand = "<start-command>"
+   $server = Start-Process -FilePath "powershell" -ArgumentList @("-NoProfile", "-Command", $devServerCommand) -PassThru
+   $DEV_SERVER_PID = $server.Id
+   ```
+
+   Wait for server to be ready: poll `http://localhost:$DEV_PORT` until it returns 200 or 302 (max 30 seconds, 2s interval):
    ```powershell
-   npm install -g @playwright/cli@latest
-   playwright-cli --version
+   $ready = $false
+   for ($i = 0; $i -lt 15; $i++) {
+     try {
+       $response = Invoke-WebRequest -Uri "http://localhost:$DEV_PORT" -UseBasicParsing -TimeoutSec 2
+       if ($response.StatusCode -in @(200, 302)) { $ready = $true; break }
+     } catch {
+       Start-Sleep -Seconds 2
+     }
+   }
+   if (-not $ready) { "DEV_SERVER_NOT_READY" }
    ```
-4. If no browser tool is usable after these steps, append `## Browser Verification: SKIPPED — no usable browser tool` to `context-snapshot.md`, then continue to reporting/checkpoint.
+4. Open the app in playwright-cli: `playwright-cli open "http://localhost:$DEV_PORT"`
+5. If the page requires authentication, use playwright-cli to register a test user and log in first
+
+**Step 2 — Verification**:
+
+Use `playwright-cli snapshot` on the running app to discover actual element refs, then verify these goals:
+{{BROWSER_VERIFY_STEPS}}
+
+Construct your verification workflow based on:
+1. The playwright-cli skill documentation (read in Step 0d)
+2. The `playwright-cli --help` output (captured in Step 0b)
+3. The current task's Verification Gates and implemented features
+
+Decide the concrete playwright-cli actions (click, fill, snapshot, screenshot, etc.) yourself based on the snapshot output and your knowledge of the implemented code. The goals above describe WHAT to verify — you determine HOW using playwright-cli commands.
+
+Take a final screenshot for evidence: `playwright-cli screenshot`
+
+**Step 3 — Cleanup (REQUIRED — you started it, you stop it)**:
+
+1. Close the playwright-cli browser: `playwright-cli close`
+2. Stop the dev server process and any remaining process bound to the dev server port:
+   ```powershell
+   if ($DEV_SERVER_PID) { Stop-Process -Id $DEV_SERVER_PID -Force -ErrorAction SilentlyContinue }
+   Get-NetTCPConnection -LocalPort ([int]$DEV_PORT) -ErrorAction SilentlyContinue |
+     Select-Object -ExpandProperty OwningProcess -Unique |
+     ForEach-Object { Stop-Process -Id $_ -Force -ErrorAction SilentlyContinue }
+   ```
+
+If you choose opencli, follow this workflow:
+
+**Using: opencli** (reuses Chrome logged-in sessions)
+
+**CRITICAL CONSTRAINT — opencli browser ONLY**:
+- You MUST use `opencli browser` for ALL browser interactions in this phase
+- All browser actions go through `opencli browser <command>` in the PowerShell tool
 
-Use `opencli` instead of `playwright-cli` only when the scenario requires an existing Chrome login/session or third-party integration cookies.
+**Step 0 — OpenCLI Readiness Check (BLOCKING)**:
 
-Record your choice:
+0a. Check if `opencli` is installed:
 ```powershell
-$BROWSER_TOOL = "playwright-cli"   # or "opencli" or "skipped"
-"Selected browser tool: $BROWSER_TOOL"
+$opencli = Get-Command opencli -ErrorAction SilentlyContinue
+if ($opencli) { opencli --version } else { "NOT_INSTALLED" }
 ```
+If `NOT_INSTALLED`: `npm install -g @jackwener/opencli@latest`. If installation fails, log `## Browser Verification: SKIPPED — opencli installation failed` and proceed.
+
+0b. Verify Browser Bridge: `opencli doctor`. If fails, log skip and proceed.
 
-If `$BROWSER_TOOL -eq "skipped"`, do NOT start a dev server and do NOT run browser commands. Go directly to result reporting and the checkpoint update.
+0c. Learn usage:
+```powershell
+opencli browser --help 2>$null
+if ($LASTEXITCODE -ne 0) { opencli --help }
+```
 
-**Dev server setup**:
+**Step 1 — Start Dev Server**: use the same port detection and server lifecycle pattern as the playwright-cli path:
 ```powershell
 $DEV_PORT = "{{DEV_PORT}}"
-if ($DEV_PORT -eq "{{DEV_PORT}}") {
-  $detected = node -e "const p=require('./package.json'); const s = p.scripts ? p.scripts.dev : ''; const m=s.match(/-p\s+(\d+)/); console.log(m?m[1]:'')"
-  if ($detected) { $DEV_PORT = $detected } else { $DEV_PORT = "3000" }
+if ($DEV_PORT -eq "{{DEV_PORT}}" -or [string]::IsNullOrWhiteSpace($DEV_PORT)) {
+  $detectedPort = ""
+  if (Test-Path -LiteralPath "package.json") {
+    $detectedPort = node -e "const p=require('./package.json'); const s=(p.scripts?.dev) || ''; const m=s.match(/-p\s+(\d+)/); console.log(m?m[1]:'')"
+  }
+  if (-not $detectedPort -and $env:NEXT_PUBLIC_SITE_URL -match ':([0-9]+)') {
+    $detectedPort = $Matches[1]
+  }
+  if ($detectedPort) { $DEV_PORT = $detectedPort } else { $DEV_PORT = "3000" }
 }
 "Detected DEV_PORT=$DEV_PORT"
+```
+```powershell
 $portBusy = Get-NetTCPConnection -LocalPort ([int]$DEV_PORT) -ErrorAction SilentlyContinue
 if ($portBusy) { "PORT_IN_USE" } else { "PORT_FREE" }
-
-# Replace <start-command> with the project-specific dev command.
-$server = Start-Process -FilePath "powershell" -ArgumentList @("-NoProfile", "-Command", "<start-command>") -PassThru
+$devServerCommand = "<start-command>"
+$server = Start-Process -FilePath "powershell" -ArgumentList @("-NoProfile", "-Command", $devServerCommand) -PassThru
 $DEV_SERVER_PID = $server.Id
 ```
 
-Wait for readiness:
+Wait for server to be ready: poll `http://localhost:$DEV_PORT` until it returns 200 or 302 (max 30 seconds, 2s interval):
 ```powershell
 $ready = $false
 for ($i = 0; $i -lt 15; $i++) {
   try {
     $response = Invoke-WebRequest -Uri "http://localhost:$DEV_PORT" -UseBasicParsing -TimeoutSec 2
     if ($response.StatusCode -in @(200, 302)) { $ready = $true; break }
-  } catch { Start-Sleep -Seconds 2 }
+  } catch {
+    Start-Sleep -Seconds 2
+  }
 }
 if (-not $ready) { "DEV_SERVER_NOT_READY" }
 ```
 
-**Verification goals**:
+Start server, wait for ready, then:
+```powershell
+opencli browser open "http://localhost:$DEV_PORT"
+if ($LASTEXITCODE -eq 0) { opencli browser state }
+```
+
+**Step 2 — Verification**:
+
+Use `opencli browser state` to discover elements with `[N]` indices, then verify:
 {{BROWSER_VERIFY_STEPS}}
 
-Use the selected browser tool to inspect current page state, perform actions, and take a final screenshot:
-- `playwright-cli open http://localhost:$DEV_PORT`, `playwright-cli snapshot`, `playwright-cli screenshot`, `playwright-cli close`
-- `opencli browser open http://localhost:$DEV_PORT`, `opencli browser state`, `opencli browser screenshot`, `opencli browser close`
+Chain commands in PowerShell with semicolons and inspect each result, for example: `opencli browser click <N>; opencli browser wait time 1; opencli browser state`
+
+**Step 3 — Cleanup**:
+1. `opencli browser close`
+2. Stop the dev server process and any remaining process bound to the dev server port:
+   ```powershell
+   if ($DEV_SERVER_PID) { Stop-Process -Id $DEV_SERVER_PID -Force -ErrorAction SilentlyContinue }
+   Get-NetTCPConnection -LocalPort ([int]$DEV_PORT) -ErrorAction SilentlyContinue |
+     Select-Object -ExpandProperty OwningProcess -Unique |
+     ForEach-Object { Stop-Process -Id $_ -Force -ErrorAction SilentlyContinue }
+   ```
 
-Base concrete actions on the Task Contract's Verification Gates.
+**Step 4 — Reporting**:
 
-**Cleanup**:
-```powershell
-if ($DEV_SERVER_PID) { Stop-Process -Id $DEV_SERVER_PID -Force -ErrorAction SilentlyContinue }
-Get-NetTCPConnection -LocalPort ([int]$DEV_PORT) -ErrorAction SilentlyContinue |
-  Select-Object -ExpandProperty OwningProcess -Unique |
-  ForEach-Object { Stop-Process -Id $_ -Force -ErrorAction SilentlyContinue }
+Append results to `context-snapshot.md`:
+```
+## Browser Verification
+Tool: <playwright-cli or opencli>
+URL: http://localhost:$DEV_PORT
+Dev Server Command: <actual command used>
+Tool version: <version>
+Steps executed: [list of commands used]
+Screenshot: [path]
+Result: PASS / FAIL (reason)
+Server cleanup: confirmed
+Browser cleanup: confirmed
 ```
 
-Append results to `context-snapshot.md` with tool, URL, commands used, screenshot path, PASS/FAIL/SKIPPED reason, and cleanup status.
+If verification fails, log the failure details but continue to commit. Failures do NOT block the commit, but you MUST attempt verification and MUST clean up the dev server.
 
-**Checkpoint update**:
+**Checkpoint update**: Run the update script to set step `browser-verification` to `"completed"`:
 ```powershell
-Invoke-PrizmPython {{PIPELINE_DIR}}\scripts\update-checkpoint.py --checkpoint-path {{CHECKPOINT_PATH}} --step browser-verification --status completed
+Invoke-PrizmPython {{PIPELINE_DIR}}\scripts\update-checkpoint.py `
+  --checkpoint-path {{CHECKPOINT_PATH}} `
+  --step browser-verification `
+  --status completed
 ```

package/bundled/dev-pipeline-windows/templates/sections/phase-browser-verification-opencli.md

@@ -1,63 +1,112 @@
 ### Browser Verification (opencli) — MANDATORY
 
-You MUST execute this phase with `opencli browser`. Use native PowerShell commands for setup, server lifecycle, and cleanup.
+You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without actually running opencli.
 
-**Readiness**:
+**Using: opencli** (reuses Chrome logged-in sessions)
+
+**CRITICAL CONSTRAINT — opencli browser ONLY**:
+- You MUST use `opencli browser` for ALL browser interactions in this phase
+- All browser actions go through `opencli browser <command>` in the PowerShell tool
+
+**Step 0 — OpenCLI Readiness Check (BLOCKING)**:
+
+0a. Check if `opencli` is installed:
 ```powershell
 $opencli = Get-Command opencli -ErrorAction SilentlyContinue
-if ($opencli) { opencli --version } else { "OPENCLI:NOT_INSTALLED" }
-opencli doctor
+if ($opencli) { opencli --version } else { "NOT_INSTALLED" }
 ```
+If `NOT_INSTALLED`: `npm install -g @jackwener/opencli@latest`. If installation fails, log `## Browser Verification: SKIPPED — opencli installation failed` and proceed.
+
+0b. Verify Browser Bridge: `opencli doctor`. If fails, log skip and proceed.
 
-If opencli is not available, install it:
+0c. Learn usage:
 ```powershell
-npm install -g @jackwener/opencli@latest
-opencli --version
+opencli browser --help 2>$null
+if ($LASTEXITCODE -ne 0) { opencli --help }
 ```
 
-**Dev server setup**:
+**Step 1 — Start Dev Server**: use the same port detection and server lifecycle pattern as the playwright-cli path:
 ```powershell
 $DEV_PORT = "{{DEV_PORT}}"
-if ($DEV_PORT -eq "{{DEV_PORT}}") {
-  $detected = node -e "const p=require('./package.json'); const s = p.scripts ? p.scripts.dev : ''; const m=s.match(/-p\s+(\d+)/); console.log(m?m[1]:'')"
-  if ($detected) { $DEV_PORT = $detected } else { $DEV_PORT = "3000" }
+if ($DEV_PORT -eq "{{DEV_PORT}}" -or [string]::IsNullOrWhiteSpace($DEV_PORT)) {
+  $detectedPort = ""
+  if (Test-Path -LiteralPath "package.json") {
+    $detectedPort = node -e "const p=require('./package.json'); const s=(p.scripts?.dev) || ''; const m=s.match(/-p\s+(\d+)/); console.log(m?m[1]:'')"
+  }
+  if (-not $detectedPort -and $env:NEXT_PUBLIC_SITE_URL -match ':([0-9]+)') {
+    $detectedPort = $Matches[1]
+  }
+  if ($detectedPort) { $DEV_PORT = $detectedPort } else { $DEV_PORT = "3000" }
 }
 "Detected DEV_PORT=$DEV_PORT"
+```
+```powershell
 $portBusy = Get-NetTCPConnection -LocalPort ([int]$DEV_PORT) -ErrorAction SilentlyContinue
 if ($portBusy) { "PORT_IN_USE" } else { "PORT_FREE" }
-$server = Start-Process -FilePath "powershell" -ArgumentList @("-NoProfile", "-Command", "<start-command>") -PassThru
+$devServerCommand = "<start-command>"
+$server = Start-Process -FilePath "powershell" -ArgumentList @("-NoProfile", "-Command", $devServerCommand) -PassThru
 $DEV_SERVER_PID = $server.Id
 ```
 
-Wait for readiness:
+Wait for server to be ready: poll `http://localhost:$DEV_PORT` until it returns 200 or 302 (max 30 seconds, 2s interval):
 ```powershell
 $ready = $false
 for ($i = 0; $i -lt 15; $i++) {
   try {
     $response = Invoke-WebRequest -Uri "http://localhost:$DEV_PORT" -UseBasicParsing -TimeoutSec 2
     if ($response.StatusCode -in @(200, 302)) { $ready = $true; break }
-  } catch { Start-Sleep -Seconds 2 }
+  } catch {
+    Start-Sleep -Seconds 2
+  }
 }
 if (-not $ready) { "DEV_SERVER_NOT_READY" }
 ```
 
-**Verification goals**:
+Start server, wait for ready, then:
+```powershell
+opencli browser open "http://localhost:$DEV_PORT"
+if ($LASTEXITCODE -eq 0) { opencli browser state }
+```
+
+**Step 2 — Verification**:
+
+Use `opencli browser state` to discover elements with `[N]` indices, then verify:
 {{BROWSER_VERIFY_STEPS}}
 
-Use `opencli browser open http://localhost:$DEV_PORT`, `opencli browser state`, indexed interaction commands from `opencli browser --help`, and `opencli browser screenshot`.
+Chain commands in PowerShell with semicolons and inspect each result, for example: `opencli browser click <N>; opencli browser wait time 1; opencli browser state`
 
-**Cleanup**:
-```powershell
-opencli browser close
-if ($DEV_SERVER_PID) { Stop-Process -Id $DEV_SERVER_PID -Force -ErrorAction SilentlyContinue }
-Get-NetTCPConnection -LocalPort ([int]$DEV_PORT) -ErrorAction SilentlyContinue |
-  Select-Object -ExpandProperty OwningProcess -Unique |
-  ForEach-Object { Stop-Process -Id $_ -Force -ErrorAction SilentlyContinue }
+**Step 3 — Cleanup**:
+1. `opencli browser close`
+2. Stop the dev server process and any remaining process bound to the dev server port:
+   ```powershell
+   if ($DEV_SERVER_PID) { Stop-Process -Id $DEV_SERVER_PID -Force -ErrorAction SilentlyContinue }
+   Get-NetTCPConnection -LocalPort ([int]$DEV_PORT) -ErrorAction SilentlyContinue |
+     Select-Object -ExpandProperty OwningProcess -Unique |
+     ForEach-Object { Stop-Process -Id $_ -Force -ErrorAction SilentlyContinue }
+   ```
+
+**Step 4 — Reporting**:
+
+Append results to `context-snapshot.md`:
+```
+## Browser Verification
+Tool: <playwright-cli or opencli>
+URL: http://localhost:$DEV_PORT
+Dev Server Command: <actual command used>
+Tool version: <version>
+Steps executed: [list of commands used]
+Screenshot: [path]
+Result: PASS / FAIL (reason)
+Server cleanup: confirmed
+Browser cleanup: confirmed
 ```
 
-Append results to `context-snapshot.md` with URL, command used, opencli version, steps executed, screenshot path, PASS/FAIL reason, and cleanup status.
+If verification fails, log the failure details but continue to commit. Failures do NOT block the commit, but you MUST attempt verification and MUST clean up the dev server.
 
-**Checkpoint update**:
+**Checkpoint update**: Run the update script to set step `browser-verification` to `"completed"`:
 ```powershell
-Invoke-PrizmPython {{PIPELINE_DIR}}\scripts\update-checkpoint.py --checkpoint-path {{CHECKPOINT_PATH}} --step browser-verification --status completed
+Invoke-PrizmPython {{PIPELINE_DIR}}\scripts\update-checkpoint.py `
+  --checkpoint-path {{CHECKPOINT_PATH}} `
+  --step browser-verification `
+  --status completed
 ```