prizmkit 1.1.108 → 1.1.110

package/bundled/dev-pipeline/scripts/utils.py

@@ -9,8 +9,50 @@ import json
 import logging
 import os
 import re
+import shlex
 import sys
 
+_PIPELINE_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+if _PIPELINE_ROOT not in sys.path:
+    sys.path.insert(0, _PIPELINE_ROOT)
+
+
+def shell_quote(value):
+    """Return a shell-safe token for prompt command examples."""
+    return shlex.quote(str(value))
+
+
+def runtime_python_command():
+    """Return the current Python executable for rendered prompt commands."""
+    return shell_quote(sys.executable or "python3")
+
+
+def runtime_helper_command(script_dir):
+    """Return the installed-project helper command prefix for prompt templates."""
+    helper_path = os.path.join(
+        ".prizmkit", "dev-pipeline", "scripts", "prizmkit-runtime-helper.py"
+    )
+    return "{} {}".format(runtime_python_command(), helper_path)
+
+
+def checkpoint_python_command():
+    """Return the checkpoint update Python command prefix for prompt templates."""
+    return "{} {}".format(
+        runtime_python_command(),
+        os.path.join(".prizmkit", "dev-pipeline", "scripts", "update-checkpoint.py"),
+    )
+
+
+def helper_replacements(script_dir):
+    """Return common prompt placeholders for Python runtime helpers."""
+    return {
+        "{{PYTHON_CMD}}": runtime_python_command(),
+        "{{RUNTIME_HELPER_CMD}}": runtime_helper_command(script_dir),
+        "{{CHECKPOINT_PYTHON_CMD}}": checkpoint_python_command(),
+    }
+
+
+
 
 def load_json_file(path):
     """Load and return parsed JSON from a file.
@@ -99,7 +141,7 @@ A checkpoint file tracks your progress through this workflow:
 Use this helper to update checkpoint status. Do not hand-edit `workflow-checkpoint.json` directly.
 
 ```bash
-python3 .prizmkit/dev-pipeline/scripts/update-checkpoint.py \\
+{{CHECKPOINT_PYTHON_CMD}} \\
   --checkpoint-path {{CHECKPOINT_PATH}} \\
   --step <step-id-or-skill-name> \\
   --status <in_progress|completed|failed|skipped> \\
@@ -560,84 +602,13 @@ def enrich_global_context(global_context, project_root):
     return global_context
 
 
-
-def read_json_object(path):
-    """Read a JSON object, returning an empty dict when unavailable."""
-    try:
-        with open(path, "r", encoding="utf-8") as f:
-            data = json.load(f)
-    except (IOError, OSError, json.JSONDecodeError):
-        return {}
-    return data if isinstance(data, dict) else {}
-
-
-def platform_from_command(command):
-    """Map an AI CLI command/config value to a PrizmKit platform name."""
-    cmd = str(command or "").strip().lower()
-    if not cmd:
-        return ""
-    base = os.path.basename(cmd.split()[0])
-    if base in ("claude", "claude-code") or "claude" in base:
-        return "claude"
-    if base in ("codex", "openai-codex") or "codex" in base:
-        return "codex"
-    if base in ("cbc", "codebuddy") or "codebuddy" in base:
-        return "codebuddy"
-    return ""
-
-
-def valid_prompt_platform(value):
-    """Normalize a platform value for prompt path rendering."""
-    value = str(value or "").strip().lower()
-    if value in ("claude", "codex", "codebuddy"):
-        return value
-    return ""
-
-
 def resolve_prompt_platform(project_root):
-    """Resolve the platform whose agent paths should appear in prompts.
-
-    Explicit ``PRIZMKIT_PLATFORM`` wins. Otherwise prefer active/configured AI
-    CLI because mixed installs contain several platform directories. Filesystem
-    markers are only a final fallback.
-    """
-    explicit = valid_prompt_platform(os.environ.get("PRIZMKIT_PLATFORM", ""))
-    if explicit:
-        return explicit
-
-    for env_name in ("AI_CLI", "CLAUDECODE", "CLAUDE_CODE"):
-        detected = platform_from_command(os.environ.get(env_name, ""))
-        if detected:
-            return detected
-
-    config = read_json_object(os.path.join(project_root, ".prizmkit", "config.json"))
-    for key in ("ai_cli", "aiCli"):
-        detected = platform_from_command(config.get(key, ""))
-        if detected:
-            return detected
-    detected = valid_prompt_platform(config.get("platform", ""))
-    if detected:
-        return detected
-
-    manifest = read_json_object(os.path.join(project_root, ".prizmkit", "manifest.json"))
-    options = manifest.get("options", {}) if isinstance(manifest.get("options"), dict) else {}
-    for value in (manifest.get("aiCli", ""), options.get("aiCli", "")):
-        detected = platform_from_command(value)
-        if detected:
-            return detected
-    detected = valid_prompt_platform(manifest.get("platform", ""))
-    if detected:
-        return detected
-
-    marker_order = (
-        ("claude", os.path.join(project_root, ".claude", "agents")),
-        ("codex", os.path.join(project_root, ".codex", "agents")),
-        ("codebuddy", os.path.join(project_root, ".codebuddy", "agents")),
-    )
-    for candidate, marker in marker_order:
-        if os.path.isdir(marker):
-            return candidate
+    """Resolve the platform whose agent paths should appear in prompts."""
+    from prizmkit_runtime.platform_detection import resolve_platform
 
+    resolution = resolve_platform(project_root)
+    if resolution.platform:
+        return resolution.platform
     raise RuntimeError(
         "PrizmKit agents not found. None of .claude/agents/, .codex/agents/, or .codebuddy/agents/ exists. "
         "Run `npx prizmkit install` first, set .prizmkit/config.json ai_cli/platform, or set PRIZMKIT_PLATFORM=claude|codex|codebuddy explicitly."

package/bundled/dev-pipeline/templates/bootstrap-tier1.md

@@ -46,15 +46,15 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 
 1. **context-snapshot.md is your single source of truth** — After Phase 1 builds it, ALWAYS read context-snapshot.md instead of re-reading individual source files
 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. **Never re-read unmodified files** — Once you have read a file into context, do NOT read it again unless it was modified by an Edit/Write operation after your last read. Use `grep -n '<pattern>' <file>` or `sed -n '<start>,<end>p' <file>` for targeted line lookups instead of full-file Read. Before issuing a Read, ask yourself: "Have I read this file before, and has it changed since?" If the answer is "no, it hasn't changed" — do NOT read it. This applies to all files including those summarized in context-snapshot.md Section 4. Subagents (Critic, Reviewer) must receive context-snapshot.md and rely on it rather than independently re-reading the same files the orchestrator already read.
+3. **Never re-read unmodified files** — Once you have read a file into context, do NOT read it again unless it was modified by an Edit/Write operation after your last read. Use platform file/search tools for targeted lookup; when shell-free helper lookup is needed, run `{{RUNTIME_HELPER_CMD}} text search <file> --pattern "<pattern>" --json`, then read only the smallest bounded range with the platform file-reading tool instead of full-file Read. Before issuing a Read, ask yourself: "Have I read this file before, and has it changed since?" If the answer is "no, it hasn't changed" — do NOT read it. This applies to all files including those summarized in context-snapshot.md Section 4. Subagents (Critic, Reviewer) must receive context-snapshot.md and rely on it rather than independently re-reading the same files the orchestrator already read.
 4. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
 4. **One task at a time** — In Phase 3 (implement), 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 /tmp/out.txt | tail -20`), then scan the head/tail to identify relevant fields, and use targeted filtering (`grep`, `sed`, `awk`) 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 command output to a temp file using the command/tool output option or the host-appropriate redirection, then inspect only the final relevant lines and use targeted search helpers to extract 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 Phase 1-3. All changes are committed once at the end in Phase 4 via `/prizmkit-committer`.
-7. **Capture test output once** — When running test suites, always use `<test-command> 2>&1 | tee /tmp/test-out.txt | tail -20`. Then grep `/tmp/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, capture output once to `/tmp/test-out.txt` using the command/tool output option or the host-appropriate redirection, surface only the final relevant lines, then search `/tmp/test-out.txt` for details. Never re-run the suite just to apply a different filter.
 9. **Package version verification (BLOCKING)** — Before writing ANY dependency version, verify it exists via registry query (`npm view <pkg> dist-tags.latest`, `pip index versions <pkg>`, etc.). NEVER guess version numbers.
 10. **Build artifact hygiene** — After build/compile, ensure output is in `.gitignore`. Never commit binaries/build output.
-11. **Read offset safety (BLOCKING)** — If Read returns "shorter than offset"/"File is empty"/"Wasted call" — do NOT retry same offset. Run `wc -l <file>` to get real line count, then `sed -n` for exact range. 2 consecutive offset errors → STOP Reading that file. Never guess offsets — `grep -n '<anchor>'` first.
+11. **Read offset safety (BLOCKING)** — If Read returns "shorter than offset"/"File is empty"/"Wasted call" — do NOT retry same offset. Use the platform file-reading tool to refresh bounded line information, or locate an anchor with `{{RUNTIME_HELPER_CMD}} text search <file> --pattern "<anchor>" --json` before reading a small bounded range. 2 consecutive offset errors → STOP Reading that file. Never guess offsets or prescribe POSIX-only lookup commands.
 
 ---
 
@@ -72,7 +72,7 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 {{IF_INIT_NEEDED}}
 ### Phase 0: Project Bootstrap
 - Run `/prizmkit-init` (invoke the prizmkit-init skill)
-- Run `python3 {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}`
+- Run `{{PYTHON_CMD}} {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}`
 - **CP-0**: Verify `.prizmkit/prizm-docs/root.prizm`, `.prizmkit/config.json` exist
 {{END_IF_INIT_NEEDED}}
 {{IF_INIT_DONE}}
@@ -82,22 +82,22 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 ### Phase 1: Build Context Snapshot
 
 ```bash
-ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md 2>/dev/null && echo "EXISTS" || echo "MISSING"
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md
 ```
 
 If MISSING — build it now:
 1. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1 prizm docs
-2. Detect source code directories: read KEY_FILES and STRUCTURE sections from `root.prizm` to identify where source code lives (e.g. `src/`, `app/`, `lib/`, `cmd/`, `packages/`, or project root). If `root.prizm` is missing, scan the project tree:
+2. Detect source code directories from KEY_FILES and STRUCTURE sections in `root.prizm`; if root docs are unavailable, use the helper to list likely source files:
    ```bash
-   find . -maxdepth 2 -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rb" -o -name "*.rs" \) -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/vendor/*' | head -30
+   {{RUNTIME_HELPER_CMD}} artifact source-files . --json
    ```
-   Identify the top-level source directories from the results.
+   Identify the top-level source directories from the helper output.
 3. Scan the detected source directories for files related to this feature; read each one
 4. Write `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`:
    - **Section 1 — Feature Brief**: feature description + acceptance criteria (copy from above)
-   - **Section 2 — Project Structure**: run the following to get a visual directory tree, then paste output:
+   - **Section 2 — Project Structure**: run the helper to get a visual directory tree, then paste output:
      ```bash
-     find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/__pycache__/*' -not -path '*/vendor/*' | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
+     {{RUNTIME_HELPER_CMD}} artifact tree . --max-depth 2
      ```
    - **Section 3 — Prizm Context**: content of root.prizm and relevant L1/L2 docs
    - **Section 4 — Existing Source Files**: **full verbatim content** of each related file in fenced code blocks (with `### path/to/file` heading and line count). Include ALL files needed for implementation and review — downstream phases read this section instead of re-reading individual source files
@@ -106,7 +106,7 @@ If MISSING — build it now:
 ### Phase 2: Plan & Tasks
 
 ```bash
-ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}
 ```
 
 If plan.md missing, run `/prizmkit-plan` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to generate `plan.md`:
@@ -126,9 +126,9 @@ Before proceeding past CP-1:
 **Build artifacts**: After any build/compile command (`go build`, `npm run build`, `tsc`, etc.), ensure the output binary or build directory is in `.gitignore`:
 ```bash
 # Example for Go
-grep -q '^/binary-name$' .gitignore || echo '/binary-name' >> .gitignore
+{{RUNTIME_HELPER_CMD}} text contains .gitignore --pattern "/binary-name" --found-marker IGNORED --missing-marker NEEDS_IGNORE_ENTRY
 ```
-Never commit compiled binaries, build output, or generated artifacts.
+If the helper prints `NEEDS_IGNORE_ENTRY`, edit `.gitignore` and add `/binary-name` as a single line. Never commit compiled binaries, build output, or generated artifacts.
 
 **3a.** Run `/prizmkit-implement` — this handles the implementation cycle:
 - Reads plan.md Tasks section from `.prizmkit/specs/{{FEATURE_SLUG}}/`
@@ -157,7 +157,7 @@ The skill runs an internal review-fix loop (Reviewer Agent → filter → orches
 **Gate Check — Review Report**:
 After `/prizmkit-code-review` returns, verify the review report:
 ```bash
-grep -q "## Verdict" .prizmkit/specs/{{FEATURE_SLUG}}/review-report.md && echo "GATE:PASS" || echo "GATE:MISSING"
+{{RUNTIME_HELPER_CMD}} text contains .prizmkit/specs/{{FEATURE_SLUG}}/review-report.md --pattern "## Verdict"
 ```
 If GATE:MISSING:
 - Do not re-run `/prizmkit-code-review` in an unbounded report-repair loop.
@@ -177,8 +177,8 @@ Run `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLU
 
 Before invoking the skill, create a current-run marker so stale reports are ignored:
 ```bash
-mkdir -p .prizmkit/specs/{{FEATURE_SLUG}}
-touch .prizmkit/specs/{{FEATURE_SLUG}}/.prizmkit-test-started
+{{RUNTIME_HELPER_CMD}} artifact ensure-dir .prizmkit/specs/{{FEATURE_SLUG}}
+{{RUNTIME_HELPER_CMD}} artifact touch .prizmkit/specs/{{FEATURE_SLUG}}/.prizmkit-test-started
 ```
 
 Gate requirements:
@@ -209,13 +209,13 @@ You MUST execute this phase. Do NOT skip it.
 
 0a. Check if `playwright-cli` is installed:
 ```bash
-which playwright-cli 2>/dev/null && playwright-cli --version 2>/dev/null || echo "NOT_INSTALLED"
+{{RUNTIME_HELPER_CMD}} executable version playwright-cli --arg=--version
 ```
 If output is `NOT_INSTALLED`, install it:
 ```bash
 npm install -g @playwright/cli@latest
 ```
-Then verify installation succeeded: `playwright-cli --version`. If installation fails, log `## Browser Verification: SKIPPED — playwright-cli installation failed` in context-snapshot.md and proceed to the next phase.
+Then verify installation succeeded: `{{RUNTIME_HELPER_CMD}} executable version playwright-cli --arg=--version`. If installation fails, log `## Browser Verification: SKIPPED — playwright-cli installation failed` in context-snapshot.md and proceed to the next phase.
 
 0b. Learn playwright-cli usage (run once per session):
 ```bash
@@ -224,21 +224,9 @@ playwright-cli --help
 
 0c. Check if playwright-cli skill is installed for the current AI platform:
 ```bash
-CURRENT_PLATFORM=""
-if which claude >/dev/null 2>&1; then
-  CURRENT_PLATFORM="claude"; SKILL_DIR="$HOME/.claude/skills"
-elif which cbc >/dev/null 2>&1; then
-  CURRENT_PLATFORM="codebuddy"; SKILL_DIR="$HOME/.cbc/skills"
-else
-  CURRENT_PLATFORM="unknown"
-fi
-if [ -d "$SKILL_DIR/playwright-cli" ] || ls "$SKILL_DIR"/playwright* 2>/dev/null | grep -q .; then
-  echo "SKILL_EXISTS"
-else
-  echo "SKILL_MISSING"
-fi
+{{RUNTIME_HELPER_CMD}} platform skill playwright-cli --prefix
 ```
-If `SKILL_MISSING`: run `playwright-cli install --skills`. If current platform is NOT claude, copy installed skill from `$HOME/.claude/skills/playwright-cli` to `$SKILL_DIR/playwright-cli`.
+If `SKILL_MISSING`: run `playwright-cli install --skills`. If current platform is NOT claude, copy the installed skill from the Claude user skills directory to the path shown by the helper output for the current platform.
 
 0d. Read the installed playwright-cli skill (SKILL.md) for workflow guidance. Use its recommended patterns to construct your verification flow.
 
@@ -247,29 +235,17 @@ If `SKILL_MISSING`: run `playwright-cli install --skills`. If current platform i
 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:
-   ```bash
-   DEV_PORT={{DEV_PORT}}
-   if [ "$DEV_PORT" = "{{DEV_PORT}}" ]; then
-     DEV_PORT=$(node -e "const s=require('./package.json').scripts.dev; const m=s.match(/-p\s+(\d+)/); console.log(m?m[1]:'')")
-     if [ -z "$DEV_PORT" ]; then
-       DEV_PORT=$(echo "$NEXT_PUBLIC_SITE_URL" | sed -nE 's|.*:([0-9]+).*|\1|p')
-     fi
-     DEV_PORT=${DEV_PORT:-3000}
-   fi
-   echo "Detected DEV_PORT=$DEV_PORT"
-   ```
+2. Determine the dev server port from the pre-detected pipeline value (`{{DEV_PORT}}`) or project config. Do NOT hardcode or guess the port. Record it as `DEV_PORT` in your notes.
 3. Verify the port is available:
    ```bash
-   lsof -ti:$DEV_PORT 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
+   {{RUNTIME_HELPER_CMD}} port check {{DEV_PORT}}
    ```
 4. Start the dev server in background, capture PID:
    ```bash
-   <start-command> &
-   DEV_SERVER_PID=$!
+   {{RUNTIME_HELPER_CMD}} process start --pid-file .prizmkit/state/browser-dev-server.pid -- <start-command tokens>
    ```
-5. Wait for server to be ready: poll `http://localhost:$DEV_PORT` with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
-6. Open the app in playwright-cli: `playwright-cli open http://localhost:$DEV_PORT`
+5. Wait for server to be ready: run `{{RUNTIME_HELPER_CMD}} web wait-ready --url http://localhost:{{DEV_PORT}} --timeout 30 --interval 2`
+6. Open the app in playwright-cli: `playwright-cli open http://localhost:{{DEV_PORT}}`
 7. If the page requires authentication, use playwright-cli to register a test user and log in first
 
 **Step 2 — Verification**:
@@ -282,8 +258,8 @@ Construct your verification workflow based on: (1) the playwright-cli skill docu
 **Step 3 — Cleanup (REQUIRED — you started it, you stop it)**:
 
 1. Close the playwright-cli browser: `playwright-cli close`
-2. Kill the dev server process: `kill $DEV_SERVER_PID 2>/dev/null || true`
-3. Verify port is released: `lsof -ti:$DEV_PORT | xargs kill -9 2>/dev/null || true`
+2. Kill the dev server process: `{{RUNTIME_HELPER_CMD}} process cleanup-pid <pid-from-.prizmkit/state/browser-dev-server.pid>`
+3. Verify port is released: `{{RUNTIME_HELPER_CMD}} port check {{DEV_PORT}}`
 {{END_IF_BROWSER_TOOL_PLAYWRIGHT}}
 {{IF_BROWSER_TOOL_OPENCLI}}
 **Using: opencli** (reuses Chrome logged-in sessions)
@@ -296,45 +272,42 @@ Construct your verification workflow based on: (1) the playwright-cli skill docu
 
 0a. Check if `opencli` is installed:
 ```bash
-which opencli 2>/dev/null && opencli --version 2>/dev/null || echo "NOT_INSTALLED"
+{{RUNTIME_HELPER_CMD}} executable version opencli --arg=--version
 ```
 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.
 
-0c. Learn usage: `opencli browser --help 2>/dev/null || opencli --help`
+0c. Learn usage: `opencli browser --help`
 
-**Step 1 — Start Dev Server**: (same port detection as playwright path)
-```bash
-DEV_PORT={{DEV_PORT}}
-if [ "$DEV_PORT" = "{{DEV_PORT}}" ]; then
-  DEV_PORT=$(node -e "const s=require('./package.json').scripts.dev; const m=s.match(/-p\s+(\d+)/); console.log(m?m[1]:'')" 2>/dev/null)
-  DEV_PORT=${DEV_PORT:-3000}
-fi
-```
-Start server, wait for ready, then: `opencli browser open http://localhost:$DEV_PORT && opencli browser state`
+**Step 1 — Start Dev Server**:
+1. Determine `DEV_PORT` from the pipeline value (`{{DEV_PORT}}`) or project config; do not guess.
+2. Verify port available: `{{RUNTIME_HELPER_CMD}} port check <DEV_PORT>`
+3. Start server: `{{RUNTIME_HELPER_CMD}} process start --pid-file .prizmkit/state/browser-dev-server.pid -- <start-command tokens>`
+4. Wait for ready: `{{RUNTIME_HELPER_CMD}} web wait-ready --url http://localhost:<DEV_PORT> --timeout 30 --interval 2`
+5. Open: `opencli browser open http://localhost:<DEV_PORT>`; then inspect: `opencli browser state`
 
 **Step 2 — Verification**:
 
 Use `opencli browser state` to discover elements with `[N]` indices, then verify:
    {{BROWSER_VERIFY_STEPS}}
 
-Chain commands: `opencli browser click <N> && opencli browser wait time 1 && opencli browser state`
+Run page-changing commands sequentially, then run `opencli browser state` to refresh indices.
 
 **Step 3 — Cleanup**:
 1. `opencli browser close`
-2. `kill $DEV_SERVER_PID 2>/dev/null || true`
-3. `lsof -ti:$DEV_PORT | xargs kill -9 2>/dev/null || true`
+2. `{{RUNTIME_HELPER_CMD}} process cleanup-pid <pid-from-.prizmkit/state/browser-dev-server.pid>`
+3. `{{RUNTIME_HELPER_CMD}} port check {{DEV_PORT}}`
 {{END_IF_BROWSER_TOOL_OPENCLI}}
 {{IF_BROWSER_TOOL_AUTO}}
 **Tool Selection**: Choose the best browser tool at runtime.
 
 **Step 0 — Detect available tools**:
 ```bash
-echo "=== playwright-cli ===" && which playwright-cli 2>/dev/null && playwright-cli --version 2>/dev/null || echo "NOT_INSTALLED"
-echo "=== opencli ===" && which opencli 2>/dev/null && opencli --version 2>/dev/null || echo "NOT_INSTALLED"
+{{RUNTIME_HELPER_CMD}} executable version playwright-cli --arg=--version
+{{RUNTIME_HELPER_CMD}} executable version opencli --arg=--version
 ```
-If opencli installed: `opencli doctor 2>/dev/null || echo "OPENCLI_BRIDGE_FAILED"`
+If opencli is installed, run `opencli doctor`. If it fails, mark OpenCLI unusable and choose playwright-cli or skip browser verification.
 
 **Decision table**:
 | Condition | Tool |
@@ -355,7 +328,7 @@ Append results to `context-snapshot.md`:
    ```
    ## Browser Verification
    Tool: <playwright-cli or opencli>
-   URL: http://localhost:$DEV_PORT
+   URL: http://localhost:{{DEV_PORT}}
    Dev Server Command: <actual command used>
    Tool version: <version>
    Steps executed: [list of commands used]
@@ -393,7 +366,7 @@ This single commit includes: feature code + tests + .prizmkit/prizm-docs/ update
 ```bash
 git status --short
 ```
-Working tree MUST be clean after this step. If any feature-related files remain, stage them into the SAME commit via `git add <file> && git commit --amend --no-edit`, do NOT create a separate commit.
+Working tree MUST be clean after this step. If any feature-related files remain, stage them explicitly and amend the SAME commit with `git commit --amend --no-edit`; do NOT create a separate commit.
 
 **Exception**: `session-summary.md` in the artifact directory is a local cross-session artifact generated by `/prizmkit-committer` — it is NOT committed to git. Ignore it in the clean-tree check.