prizmkit 1.1.21 → 1.1.24

package/bundled/dev-pipeline/scripts/update-refactor-status.py

@@ -96,11 +96,10 @@ def now_iso():
 
 
 def _default_status(refactor_id):
-    """Create a default refactor status object."""
+    """Create a default refactor runtime status object (no status field)."""
     now = now_iso()
     return {
         "refactor_id": refactor_id,
-        "status": "pending",
         "retry_count": 0,
         "max_retries": 3,
         "sessions": [],
@@ -112,20 +111,42 @@ def _default_status(refactor_id):
 
 
 def load_refactor_status(state_dir, refactor_id):
+    """Load runtime state from status.json for a refactor.
+
+    Returns runtime fields only (retry_count, sessions, etc.).
+    The 'status' field is NOT included — status lives exclusively
+    in refactor-list.json.
+    """
     status_path = os.path.join(state_dir, "refactors", refactor_id, "status.json")
     if not os.path.isfile(status_path):
         return _default_status(refactor_id)
     data, err = load_json_file(status_path)
     if err:
         return _default_status(refactor_id)
+    # Defensively remove status if present (legacy data)
+    data.pop("status", None)
     return data
 
 
 def save_refactor_status(state_dir, refactor_id, status_data):
+    """Write the status.json for a refactor (runtime fields only)."""
+    # Defensively strip status — it belongs in refactor-list.json
+    status_data.pop("status", None)
     status_path = os.path.join(state_dir, "refactors", refactor_id, "status.json")
     return write_json_file(status_path, status_data)
 
 
+def get_refactor_status_from_list(refactor_list_path, refactor_id):
+    """Read a single refactor's status from refactor-list.json."""
+    data, err = load_json_file(refactor_list_path)
+    if err:
+        return "pending"
+    for r in data.get("refactors", []):
+        if isinstance(r, dict) and r.get("id") == refactor_id:
+            return r.get("status", "pending")
+    return "pending"
+
+
 def update_refactor_in_list(refactor_list_path, refactor_id, new_status):
     data, err = load_json_file(refactor_list_path)
     if err:
@@ -179,7 +200,7 @@ def action_get_next(refactor_list_data, state_dir):
         print("PIPELINE_COMPLETE")
         return
 
-    # Build status map and completed set
+    # Build status map from refactor-list.json (single source of truth)
     status_map = {}
     status_data_map = {}
     for r in refactors:
@@ -188,8 +209,8 @@ def action_get_next(refactor_list_data, state_dir):
         rid = r.get("id")
         if not rid:
             continue
+        status_map[rid] = r.get("status", "pending")
         rs = load_refactor_status(state_dir, rid)
-        status_map[rid] = rs.get("status", "pending")
         status_data_map[rid] = rs
 
     completed_set = {rid for rid, st in status_map.items() if st in TERMINAL_STATUSES}
@@ -270,35 +291,30 @@ def action_update(args, refactor_list_path, state_dir):
 
     rs = load_refactor_status(state_dir, refactor_id)
 
+    # Track what status we write to refactor-list.json
+    new_status = get_refactor_status_from_list(refactor_list_path, refactor_id)
+
     if session_status == "success":
-        rs["status"] = "completed"
+        new_status = "completed"
         rs["resume_from_phase"] = None
         err = update_refactor_in_list(refactor_list_path, refactor_id, "completed")
         if err:
             error_out("Failed to update .prizmkit/plans/refactor-list.json: {}".format(err))
             return
     elif session_status in ("commit_missing", "docs_missing", "merge_conflict"):
-        # Degraded outcome: keep artifacts for retry.
-        # Write schema-valid status to refactor-list.json ("pending" for retry,
-        # "failed" if max retries exceeded). Store the granular degraded reason
-        # in status.json only (internal pipeline state, not schema-bound).
         rs["retry_count"] = rs.get("retry_count", 0) + 1
 
         if rs["retry_count"] >= max_retries:
-            rs["status"] = "failed"
-            target_status = "failed"
+            new_status = "failed"
         else:
-            # status.json keeps the granular degraded reason for diagnostics
-            rs["status"] = session_status
-            # refactor-list.json gets schema-valid "pending" (will be retried)
-            target_status = "pending"
+            new_status = "pending"
 
         rs["degraded_reason"] = session_status
         rs["resume_from_phase"] = None
         rs["sessions"] = []
         rs["last_session_id"] = None
 
-        err = update_refactor_in_list(refactor_list_path, refactor_id, target_status)
+        err = update_refactor_in_list(refactor_list_path, refactor_id, new_status)
         if err:
             error_out("Failed to update .prizmkit/plans/refactor-list.json: {}".format(err))
             return
@@ -312,17 +328,15 @@ def action_update(args, refactor_list_path, state_dir):
         )
 
         if rs["retry_count"] >= max_retries:
-            rs["status"] = "failed"
-            target_status = "failed"
+            new_status = "failed"
         else:
-            rs["status"] = "pending"
-            target_status = "pending"
+            new_status = "pending"
 
         rs["resume_from_phase"] = None
         rs["sessions"] = []
         rs["last_session_id"] = None
 
-        err = update_refactor_in_list(refactor_list_path, refactor_id, target_status)
+        err = update_refactor_in_list(refactor_list_path, refactor_id, new_status)
         if err:
             error_out("Failed to update .prizmkit/plans/refactor-list.json: {}".format(err))
             return
@@ -343,7 +357,7 @@ def action_update(args, refactor_list_path, state_dir):
 
     # Auto-skip downstream refactors when this refactor is marked as failed or skipped
     auto_skipped_refactors = []
-    if rs["status"] in ("failed", "skipped"):
+    if new_status in ("failed", "skipped"):
         auto_skipped_refactors = auto_skip_blocked_refactors(
             refactor_list_path, state_dir, refactor_id
         )
@@ -352,7 +366,7 @@ def action_update(args, refactor_list_path, state_dir):
         "action": "update",
         "refactor_id": refactor_id,
         "session_status": session_status,
-        "new_status": rs["status"],
+        "new_status": new_status,
         "retry_count": rs["retry_count"],
         "resume_from_phase": rs.get("resume_from_phase"),
         "updated_at": rs["updated_at"],
@@ -496,10 +510,9 @@ def auto_skip_blocked_refactors(refactor_list_path, state_dir, failed_refactor_i
             r["status"] = "auto_skipped"
     write_json_file(refactor_list_path, data)
 
-    # Sync status.json for each auto-skipped refactor
+    # Update timestamps in status.json for each auto-skipped refactor
     for rid in to_skip:
         rs = load_refactor_status(state_dir, rid)
-        rs["status"] = "auto_skipped"
         rs["updated_at"] = now_iso()
         save_refactor_status(state_dir, rid, rs)
 
@@ -589,8 +602,8 @@ def action_status(refactor_list_data, state_dir):
         if not rid:
             continue
 
+        rstatus = r.get("status", "pending")
         rs = load_refactor_status(state_dir, rid)
-        rstatus = rs.get("status", "pending")
         retry_count = rs.get("retry_count", 0)
         max_retries_val = rs.get("max_retries", 3)
         resume_phase = rs.get("resume_from_phase")
@@ -688,10 +701,9 @@ def action_reset(args, refactor_list_path, state_dir):
         return
 
     rs = load_refactor_status(state_dir, refactor_id)
-    old_status = rs.get("status", "unknown")
+    old_status = get_refactor_status_from_list(refactor_list_path, refactor_id)
     old_retry = rs.get("retry_count", 0)
 
-    rs["status"] = "pending"
     rs["retry_count"] = 0
     rs["sessions"] = []
     rs["last_session_id"] = None
@@ -760,10 +772,9 @@ def action_clean(args, refactor_list_path, state_dir):
 
     # 4. Reset status
     rs = load_refactor_status(state_dir, refactor_id)
-    old_status = rs.get("status", "unknown")
+    old_status = get_refactor_status_from_list(refactor_list_path, refactor_id)
     old_retry = rs.get("retry_count", 0)
 
-    rs["status"] = "pending"
     rs["retry_count"] = 0
     rs["sessions"] = []
     rs["last_session_id"] = None
@@ -834,9 +845,8 @@ def action_start(args, refactor_list_path, state_dir):
         return
 
     rs = load_refactor_status(state_dir, refactor_id)
-    old_status = rs.get("status", "pending")
+    old_status = get_refactor_status_from_list(refactor_list_path, refactor_id)
 
-    rs["status"] = "in_progress"
     rs["updated_at"] = now_iso()
 
     err = save_refactor_status(state_dir, refactor_id, rs)
@@ -988,10 +998,9 @@ def action_unskip(args, refactor_list_path, state_dir):
         error_out("Failed to write .prizmkit/plans/refactor-list.json: {}".format(err))
         return
 
-    # Reset status.json for each refactor
+    # Reset runtime fields in status.json for each refactor
     for rid in to_reset:
         rs = load_refactor_status(state_dir, rid)
-        rs["status"] = "pending"
         rs["retry_count"] = 0
         rs["sessions"] = []
         rs["last_session_id"] = None

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

@@ -189,6 +189,49 @@ Round 5: 3 failures [test_b, test_d, test_e]          ← plateau 3/3 → STOP
 
 You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without actually running 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 Bash 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:
+```bash
+which playwright-cli 2>/dev/null && playwright-cli --version 2>/dev/null || echo "NOT_INSTALLED"
+```
+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.
+
+0b. Learn playwright-cli usage (run once per session):
+```bash
+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
+```
+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`.
+
+0d. Read the installed playwright-cli skill (SKILL.md) for workflow guidance. Use its recommended patterns to construct your verification flow.
+
 **Step 1 — Start Dev Server**:
 
 You know this project's tech stack. Detect and start the dev server yourself:
@@ -196,9 +239,7 @@ 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
-   # Use pipeline-injected port if available, otherwise extract from package.json
    DEV_PORT={{DEV_PORT}}
-   # If DEV_PORT is still a placeholder, detect at runtime:
    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
@@ -225,14 +266,14 @@ You know this project's tech stack. Detect and start the dev server yourself:
 
 Use `playwright-cli snapshot` on the running app to discover actual element refs, then verify these goals:
    {{BROWSER_VERIFY_STEPS}}
-   Decide the concrete playwright-cli actions (click, fill, assert, etc.) yourself based on the snapshot output and your knowledge of the implemented code. The goals above describe WHAT to verify — you determine HOW.
 
-Take a final screenshot for evidence.
+Construct your verification workflow based on: (1) the playwright-cli skill documentation, (2) the `--help` output, (3) the current task's acceptance criteria. Decide the concrete playwright-cli actions yourself. Take a final screenshot: `playwright-cli screenshot`.
 
 **Step 3 — Cleanup (REQUIRED — you started it, you stop it)**:
 
-1. Kill the dev server process: `kill $DEV_SERVER_PID 2>/dev/null || true`
-2. Verify port is released: `lsof -ti:$DEV_PORT | xargs kill -9 2>/dev/null || true`
+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`
 
 **Step 4 — Reporting**:
 
@@ -241,10 +282,12 @@ Append results to `context-snapshot.md`:
    ## Browser Verification
    URL: http://localhost:$DEV_PORT
    Dev Server Command: <actual command used>
-   Steps executed: [list]
+   playwright-cli version: <version>
+   Steps executed: [list of playwright-cli commands used]
    Screenshot: [path]
    Result: PASS / FAIL (reason)
    Server cleanup: confirmed
+   Browser cleanup: confirmed
    ```
 
 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.

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

@@ -287,6 +287,49 @@ If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write review
 
 You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without actually running 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 Bash 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:
+```bash
+which playwright-cli 2>/dev/null && playwright-cli --version 2>/dev/null || echo "NOT_INSTALLED"
+```
+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.
+
+0b. Learn playwright-cli usage (run once per session):
+```bash
+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
+```
+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`.
+
+0d. Read the installed playwright-cli skill (SKILL.md) for workflow guidance. Use its recommended patterns to construct your verification flow.
+
 **Step 1 — Start Dev Server**:
 
 You know this project's tech stack. Detect and start the dev server yourself:
@@ -294,9 +337,7 @@ 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
-   # Use pipeline-injected port if available, otherwise extract from package.json
    DEV_PORT={{DEV_PORT}}
-   # If DEV_PORT is still a placeholder, detect at runtime:
    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
@@ -323,14 +364,14 @@ You know this project's tech stack. Detect and start the dev server yourself:
 
 Use `playwright-cli snapshot` on the running app to discover actual element refs, then verify these goals:
    {{BROWSER_VERIFY_STEPS}}
-   Decide the concrete playwright-cli actions (click, fill, assert, etc.) yourself based on the snapshot output and your knowledge of the implemented code. The goals above describe WHAT to verify — you determine HOW.
 
-Take a final screenshot for evidence.
+Construct your verification workflow based on: (1) the playwright-cli skill documentation, (2) the `--help` output, (3) the current task's acceptance criteria. Decide the concrete playwright-cli actions yourself. Take a final screenshot: `playwright-cli screenshot`.
 
 **Step 3 — Cleanup (REQUIRED — you started it, you stop it)**:
 
-1. Kill the dev server process: `kill $DEV_SERVER_PID 2>/dev/null || true`
-2. Verify port is released: `lsof -ti:$DEV_PORT | xargs kill -9 2>/dev/null || true`
+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`
 
 **Step 4 — Reporting**:
 
@@ -339,10 +380,12 @@ Append results to `context-snapshot.md`:
    ## Browser Verification
    URL: http://localhost:$DEV_PORT
    Dev Server Command: <actual command used>
-   Steps executed: [list]
+   playwright-cli version: <version>
+   Steps executed: [list of playwright-cli commands used]
    Screenshot: [path]
    Result: PASS / FAIL (reason)
    Server cleanup: confirmed
+   Browser cleanup: confirmed
    ```
 
 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.

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

@@ -359,6 +359,49 @@ If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write review
 
 You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without actually running 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 Bash 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:
+```bash
+which playwright-cli 2>/dev/null && playwright-cli --version 2>/dev/null || echo "NOT_INSTALLED"
+```
+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.
+
+0b. Learn playwright-cli usage (run once per session):
+```bash
+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
+```
+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`.
+
+0d. Read the installed playwright-cli skill (SKILL.md) for workflow guidance. Use its recommended patterns to construct your verification flow.
+
 **Step 1 — Start Dev Server**:
 
 You know this project's tech stack. Detect and start the dev server yourself:
@@ -366,9 +409,7 @@ 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
-   # Use pipeline-injected port if available, otherwise extract from package.json
    DEV_PORT={{DEV_PORT}}
-   # If DEV_PORT is still a placeholder, detect at runtime:
    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
@@ -395,14 +436,14 @@ You know this project's tech stack. Detect and start the dev server yourself:
 
 Use `playwright-cli snapshot` on the running app to discover actual element refs, then verify these goals:
    {{BROWSER_VERIFY_STEPS}}
-   Decide the concrete playwright-cli actions (click, fill, assert, etc.) yourself based on the snapshot output and your knowledge of the implemented code. The goals above describe WHAT to verify — you determine HOW.
 
-Take a final screenshot for evidence.
+Construct your verification workflow based on: (1) the playwright-cli skill documentation, (2) the `--help` output, (3) the current task's acceptance criteria. Decide the concrete playwright-cli actions yourself. Take a final screenshot: `playwright-cli screenshot`.
 
 **Step 3 — Cleanup (REQUIRED — you started it, you stop it)**:
 
-1. Kill the dev server process: `kill $DEV_SERVER_PID 2>/dev/null || true`
-2. Verify port is released: `lsof -ti:$DEV_PORT | xargs kill -9 2>/dev/null || true`
+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`
 
 **Step 4 — Reporting**:
 
@@ -411,10 +452,12 @@ Append results to `context-snapshot.md`:
    ## Browser Verification
    URL: http://localhost:$DEV_PORT
    Dev Server Command: <actual command used>
-   Steps executed: [list]
+   playwright-cli version: <version>
+   Steps executed: [list of playwright-cli commands used]
    Screenshot: [path]
    Result: PASS / FAIL (reason)
    Server cleanup: confirmed
+   Browser cleanup: confirmed
    ```
 
 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.

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

@@ -11,3 +11,23 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 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.
 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 /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.
+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 which 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>/dev/null`
+     - Python/pip: `pip index versions <package> 2>/dev/null | head -1`
+     - Go: `go list -m -versions <module>@latest 2>/dev/null`
+     - Rust: `cargo search <crate> --limit 1 2>/dev/null`
+   - **NEVER guess or hallucinate version numbers**. If you cannot verify a version, use `"latest"` or `"*"` as a placeholder, or omit the version constraint entirely and let the package manager resolve it
+   - If the registry query fails (network issue, package not found), you MUST either:
+     (a) Use a known-safe version you have high confidence in, OR
+     (b) Skip that dependency and document it as a manual step, OR
+     (c) Use no version constraint (e.g., `"express": "*"`)
+   - **This is a BLOCKING gate**: do NOT run `npm install` / `pip install` / `cargo build` / `go mod tidy` until ALL versions in the manifest have been verified or use open constraints
+   - Batch version lookups: query multiple packages in parallel to save time (e.g., run multiple `npm view` commands concurrently)

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

@@ -2,6 +2,77 @@
 
 You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without actually running 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 Bash 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:
+```bash
+which playwright-cli 2>/dev/null && playwright-cli --version 2>/dev/null || echo "NOT_INSTALLED"
+```
+If output is `NOT_INSTALLED`, install it:
+```bash
+npm install -g @playwright/cli@latest
+```
+Then verify installation succeeded:
+```bash
+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):
+```bash
+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:
+```bash
+# Detect AI CLI platform
+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
+  # Try to detect from environment or config
+  CURRENT_PLATFORM="unknown"
+fi
+
+# Check if playwright-cli skill exists
+if [ -d "$SKILL_DIR/playwright-cli" ] || ls "$SKILL_DIR"/playwright* 2>/dev/null | grep -q .; then
+  echo "SKILL_EXISTS"
+else
+  echo "SKILL_MISSING"
+fi
+```
+If `SKILL_MISSING`:
+```bash
+# Install playwright-cli skills (defaults to claude platform)
+playwright-cli install --skills
+```
+If the current platform is NOT claude, move the installed skill files to the correct location:
+```bash
+# Skills are installed to claude's default location — move to current platform's skill dir
+if [ "$CURRENT_PLATFORM" != "claude" ] && [ "$CURRENT_PLATFORM" != "unknown" ]; then
+  CLAUDE_SKILL_DIR="$HOME/.claude/skills"
+  if [ -d "$CLAUDE_SKILL_DIR/playwright-cli" ]; then
+    mkdir -p "$SKILL_DIR"
+    cp -r "$CLAUDE_SKILL_DIR/playwright-cli" "$SKILL_DIR/"
+    echo "Moved playwright-cli skill from claude to $CURRENT_PLATFORM"
+  fi
+fi
+```
+
+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:
@@ -39,14 +110,20 @@ You know this project's tech stack. Detect and start the dev server yourself:
 Use `playwright-cli snapshot` on the running app to discover actual element refs, then verify these goals:
 {{BROWSER_VERIFY_STEPS}}
 
-Decide the concrete playwright-cli actions (click, fill, assert, etc.) yourself based on the snapshot output and your knowledge of the implemented code. The goals above describe WHAT to verify — you determine HOW.
+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 acceptance criteria 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.
+Take a final screenshot for evidence: `playwright-cli screenshot`
 
 **Step 3 — Cleanup (REQUIRED — you started it, you stop it)**:
 
-1. Kill the dev server process: `kill $DEV_SERVER_PID 2>/dev/null || true`
-2. Verify port is released: `lsof -ti:$DEV_PORT | xargs kill -9 2>/dev/null || true`
+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`
 
 **Step 4 — Reporting**:
 
@@ -55,10 +132,12 @@ Append results to `context-snapshot.md`:
 ## Browser Verification
 URL: http://localhost:$DEV_PORT
 Dev Server Command: <actual command used>
-Steps executed: [list]
+playwright-cli version: <version>
+Steps executed: [list of playwright-cli commands used]
 Screenshot: [path]
 Result: PASS / FAIL (reason)
 Server cleanup: confirmed
+Browser cleanup: confirmed
 ```
 
 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.

package/bundled/dev-pipeline/templates/sections/phase-implement-agent.md

@@ -2,6 +2,13 @@
 
 **Build artifacts rule** (passed to Dev): After any build/compile command (`go build`, `npm run build`, `tsc`, etc.), ensure the output binary or build directory is in `.gitignore`. Never commit compiled binaries, build output, or generated artifacts.
 
+**Dependency version gate (BLOCKING — pass to Dev agent)**: Before running ANY package install command (`npm install`, `pip install`, `cargo build`, `go mod tidy`, `bundle install`, etc.):
+1. Every version number in the dependency manifest MUST be verified against the real registry (see Context Budget Rules §9)
+2. If a scaffold tool generated a `package.json` / `requirements.txt` / etc., verify the versions it wrote too — scaffold tools can emit outdated versions
+3. Do NOT proceed with install until all versions are confirmed real. Violation = wasted timeout cycles that can crash the session
+
+**Scaffold file rule (pass to Dev agent)**: After running any init/scaffold command, record generated files in context-snapshot.md under `### Scaffold Files (do not re-read)`. Never re-read these files — their content is standard boilerplate (see Context Budget Rules §8). When spawning subagents, explicitly list scaffold files so they skip reading them.
+
 **Spawn Agent**:
 | Parameter | Value |
 |-----------|-------|