prizmkit 1.1.107 → 1.1.109

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

@@ -52,21 +52,18 @@ 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-2 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. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
+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.
+4. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
 4. **One task at a time** — In Phase 4 (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.
 6. **No intermediate commits** — Do NOT run `git add`/`git commit` during Phase 1-5. All changes are committed once at the end in Phase 6 via `/prizmkit-committer`.
 7. **Batch independent operations** — Issue multiple independent `Write`/`Read` calls in a single message turn when they have no dependencies. Combine multiple `mkdir -p` into one command. Never run `npm test` twice just to apply a different grep filter — capture output to `/tmp/test-out.txt` once and grep the file.
-8. **Scaffold / generated file awareness** — Files created by scaffolding tools are boilerplate. Tag them, record in context-snapshot.md, NEVER re-read. Edit directly without reading first.
 9. **Package version verification (BLOCKING)** — Verify dependency versions via registry query before writing them. NEVER guess.
 10. **Build artifact hygiene** — After build/compile, ensure output is in `.gitignore`.
 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.
 
 ---
 
-{{LOG_SIZE_AWARENESS}}
----
-
 ## PrizmKit Directory Convention
 
 ```
@@ -82,7 +79,7 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 ## Subagent Timeout Recovery
 
 If any agent times out:
-1. `ls .prizmkit/specs/{{FEATURE_SLUG}}/` — check what exists
+1. `{{RUNTIME_HELPER_CMD}} artifact list .prizmkit/specs/{{FEATURE_SLUG}}` — check what exists
 2. If `context-snapshot.md` exists: open recovery prompt with `"Read .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md for project context and any Implementation Log/Review Notes from previous agents. Run git diff HEAD to see actual code changes already made. Do NOT re-read individual source files unless the File Manifest directs you to."` + only remaining steps + `model: "lite"`
 3. Max 2 retries per phase. After 2 failures, orchestrator completes the work directly and appends a Recovery Note to context-snapshot.md.
 
@@ -93,30 +90,22 @@ If any agent times out:
 {{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}}
-### Phase 0: Detect Test Commands
-
-**Step 1 — Detect test commands**: You know this project's tech stack. Identify ALL test commands that apply (e.g., `go test ./...`, `npm test`, `cargo test`, `pytest`, `make test`, etc.). Record them as `TEST_CMDS`.
-
-**Step 2 — Do not run tests yet**: This phase only records the commands that will be used by the post-review PrizmKit Test gate. Test execution happens after code review.
-
-> **Test Output Rule**: When the post-review gate runs, capture test output to a temp file (`tee /tmp/test-out.txt`). Then grep the file instead of re-running the suite.
-{{END_IF_INIT_DONE}}
 
 ### Step 1: Initialize
 
 1. Run init script:
-   `python3 {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}`
+   `{{PYTHON_CMD}} {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}`
 
 2. Check for existing artifacts:
-   `ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null`
+   `{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}`
 
 {{IF_FRESH_START}}
 ```bash
-python3 {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}
+{{PYTHON_CMD}} {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}
 ```
 {{END_IF_FRESH_START}}
 
@@ -124,7 +113,7 @@ python3 {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEAT
 
 Check existing artifacts first:
 ```bash
-ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}
 ```
 
 - Both (spec.md, plan.md) exist → **SKIP to CP-1**
@@ -143,11 +132,11 @@ If `EXISTING_CODE` is non-empty: your spec/plan/tasks must reflect this existing
 **Step A — Build Context Snapshot** (skip if `context-snapshot.md` already exists):
 
 1. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 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 (2-3 lines) + acceptance criteria (copy from above)
@@ -166,17 +155,18 @@ If `EXISTING_CODE` is non-empty: your spec/plan/tasks must reflect this existing
 
      ### Known TRAPS (from .prizmkit/prizm-docs/)
      - <trap entries extracted from L1/L2 docs>
-4. Confirm: `ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`
+4. Confirm: `{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`
 
 **After Step A**: Use context-snapshot.md Section 4 File Manifest to guide targeted file reads. Do NOT scan directories or read unrelated files.
 
 **Step B — Planning Artifacts** (generate only missing files):
 
 ```bash
-ls .prizmkit/specs/{{FEATURE_SLUG}}/spec.md .prizmkit/specs/{{FEATURE_SLUG}}/plan.md 2>/dev/null
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/spec.md
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/plan.md
 ```
 
-- spec.md missing: Run `/prizmkit-plan` → generate spec.md. Resolve any `[NEEDS CLARIFICATION]` markers using the feature description — do NOT pause for interactive input.
+- spec.md missing: Run `/prizmkit-plan` → generate spec.md. Resolve uncertain requirements from the feature description, existing code, and conservative existing-project patterns.
 - plan.md missing: Run `/prizmkit-plan` → generate plan.md (architecture, components, interface design, data model, testing strategy, risk assessment, and Tasks section with `[ ]` checkboxes)
 
 > All files go under `.prizmkit/specs/{{FEATURE_SLUG}}/`. Confirm each with `ls` after writing.
@@ -185,14 +175,14 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/spec.md .prizmkit/specs/{{FEATURE_SLUG}}/pla
 Before proceeding past CP-1, verify:
 1. Plan.md Data Model section references existing schema/model files (scan for `*.prisma`, `*.sql`, `migrations/`, `models/`, `*.entity.*` files; read them if not already in context-snapshot)
 2. All new tables/fields follow existing naming conventions, ID strategy, timestamp patterns, and constraint style
-3. No `[NEEDS CLARIFICATION]` remains in Data Model section — resolve by reading existing code and making a conservative choice that matches existing patterns. Document the resolution in plan.md.
+3. No unresolved data model uncertainty remains in the Data Model section — resolve by reading existing code and making a conservative choice that matches existing patterns. Document the resolution in plan.md.
 4. If a DB design decision genuinely cannot be resolved from existing code alone, document the assumption made and flag it in the Implementation Log for user review.
 
 **CP-1**: Both spec.md and plan.md exist.
 
 ### Phase 3: Analyze — Reviewer Agent
 
-Spawn Reviewer agent (Agent tool, subagent_type="prizm-dev-team-reviewer", mode="plan", run_in_background=false).
+Spawn Reviewer agent (Agent tool, subagent_type="prizm-dev-team-reviewer", mode="plan", run_in_background=false, isolation=default/no worktree). Do not request worktree isolation; this prevents AI tool-created `.claude/worktrees/...` subagent worktrees. PrizmKit pipeline-managed linked git worktrees under `.prizmkit/state/worktrees/...` are separate and controlled by `USE_WORKTREE`.
 
 Spawn failure cap: for team/config/lock errors, retry at most once for this Reviewer spawn. If the second attempt fails, do not poll for report artifacts; fix/check the plan inline or write `failure-log.md` before stopping for recovery.
 
@@ -213,7 +203,7 @@ Wait for Reviewer to return.
 
 **Guard**: Verify critic agent file exists before spawning:
 ```bash
-ls {{CRITIC_SUBAGENT_PATH}} 2>/dev/null && echo "CRITIC:READY" || echo "CRITIC:MISSING"
+{{RUNTIME_HELPER_CMD}} artifact exists {{CRITIC_SUBAGENT_PATH}} --exists-marker CRITIC:READY --missing-marker CRITIC:MISSING
 ```
 If CRITIC:MISSING — skip Phase 3.5 entirely and proceed to Phase 4. Log: "Critic agent not installed — skipping Plan Challenge."
 
@@ -221,7 +211,7 @@ If CRITIC:MISSING — skip Phase 3.5 entirely and proceed to Phase 4. Log: "Crit
 
 **If {{CRITIC_COUNT}} = 1 → Single Critic** (skip to CP-2.5 after this):
 
-Spawn Critic agent (Agent tool, subagent_type="prizm-dev-team-critic", mode="plan", run_in_background=false).
+Spawn Critic agent (Agent tool, subagent_type="prizm-dev-team-critic", mode="plan", run_in_background=false, isolation=default/no worktree). Do not request worktree isolation; this prevents AI tool-created `.claude/worktrees/...` subagent worktrees. PrizmKit pipeline-managed linked git worktrees under `.prizmkit/state/worktrees/...` are separate and controlled by `USE_WORKTREE`.
 
 Spawn failure cap: for team/config/lock errors, retry at most once for this Critic spawn. If the second attempt fails, do not poll for challenge reports; perform the plan challenge inline and record the fallback.
 
@@ -229,16 +219,17 @@ Prompt:
 > "Read {{CRITIC_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
 > **MODE: Plan Challenge**
 > 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST — Section 3 has TRAPS/RULES, Section 4 has file manifest.
-> 2. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs for affected modules.
-> 3. Read existing source files in the modules this plan touches.
-> 4. Challenge plan.md against the project's existing architecture, patterns, and style.
+> 2. Use context-snapshot.md as the shared source of truth. Do not create or enter AI tool-created `.claude/worktrees/...` subagent worktrees; use default/no worktree isolation and do not request worktree isolation.
+> 3. PrizmKit pipeline-managed linked git worktrees under `.prizmkit/state/worktrees/...` are a separate runner feature controlled by `USE_WORKTREE`; do not confuse them with AI tool-created `.claude/worktrees/...`.
+> 4. Read additional `.prizmkit/prizm-docs/` or source excerpts only when needed to verify a specific challenge.
+> 5. Challenge plan.md against the project's existing architecture, patterns, and style.
 > Write `.prizmkit/specs/{{FEATURE_SLUG}}/challenge-report.md` with findings (or 'No significant challenges')."
 
 **If {{CRITIC_COUNT}} = 3 → Multi-Critic Voting** (skip Single Critic above):
 
 **IMPORTANT**: Spawn all 3 Critics in PARALLEL (issue all 3 Agent tool calls in the SAME message turn). Do NOT wait for one before spawning the next.
 
-Spawn Critic-A, Critic-B, Critic-C simultaneously (each with mode="plan", run_in_background=false):
+Spawn Critic-A, Critic-B, Critic-C simultaneously (each with mode="plan", run_in_background=false, isolation=default/no worktree). Do not request worktree isolation; this prevents AI tool-created `.claude/worktrees/...` subagent worktrees. PrizmKit pipeline-managed linked git worktrees under `.prizmkit/state/worktrees/...` are separate and controlled by `USE_WORKTREE`:
 
 Critic-A prompt (append to base prompt above):
 > "**Focus Lens: Architecture & Scalability.** Prioritize: architectural pattern fit, scalability implications, over-engineering risks, component boundary design.
@@ -307,15 +298,6 @@ For each Verification Gate from the Task Contract, write one evidence line to Im
 
 **CP-2**: All tasks `[x]`, Implementation Log written with Gate Evidence, and blocked gates documented in `failure-log.md`. Test execution is deferred until after code review.
 
-**Checkpoint update**:
-```bash
-python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
-  --checkpoint-path .prizmkit/specs/{{FEATURE_SLUG}}/workflow-checkpoint.json \
-  --step prizmkit-implement \
-  --status completed
-```
-
-
 ### Review — Code Review
 
 Review the completed implementation before the scoped feature test gate runs. Use `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` so the code-review skill can read spec, plan, context snapshot, implementation log, and current diff artifacts. Do not require or read a prior `/prizmkit-test` report here; test generation and test-fix looping happen in the next phase.
@@ -327,7 +309,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.
@@ -345,7 +327,11 @@ Read `review-report.md` and check the Verdict:
 
 Run `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` after review and before commit.
 
-Before invoking the skill, create `.prizmkit/specs/{{FEATURE_SLUG}}/.prizmkit-test-started` so stale reports are ignored.
+Before invoking the skill, create a current-run marker so stale reports are ignored:
+```bash
+{{RUNTIME_HELPER_CMD}} artifact ensure-dir .prizmkit/specs/{{FEATURE_SLUG}}
+{{RUNTIME_HELPER_CMD}} artifact touch .prizmkit/specs/{{FEATURE_SLUG}}/.prizmkit-test-started
+```
 
 Gate requirements:
 - Generate or update tests only for this feature's changed files, changed public interfaces, and acceptance criteria.
@@ -375,13 +361,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
@@ -390,21 +376,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 installed skill from `$HOME/.claude/skills/playwright-cli` 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.
 
@@ -413,28 +387,16 @@ 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)
+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
 
@@ -448,8 +410,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}} process cleanup-port $DEV_PORT`
 {{END_IF_BROWSER_TOOL_PLAYWRIGHT}}
 {{IF_BROWSER_TOOL_OPENCLI}}
 **Using: opencli** (reuses Chrome logged-in sessions)
@@ -462,45 +424,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}} process cleanup-port $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 |

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

@@ -40,20 +40,17 @@ You are the **bug fix session agent**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}".
 
 {{GLOBAL_CONTEXT}}
 
-### Project Conventions
-
-> Read {{PLATFORM_CONVENTIONS}} for project-level coding standards, architecture decisions, and development rules.
 
 ## ⚠️ Context Budget Rules (CRITICAL)
 
 0. **NON-INTERACTIVE MODE** — NEVER ask for confirmation. Proceed autonomously.
 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.
+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 after your last read. Use `grep -n` or `sed -n` for targeted lookups instead of full-file Read. Before issuing a Read, ask: "Have I read this file before, and has it changed since?" If no — do NOT read it. Subagents must rely on context-snapshot.md rather than re-reading files the orchestrator already read.
+4. **Stay focused** — Do NOT explore code unrelated to this bug.
 4. **Minimize tool output** — Capture to temp file, scan head/tail, filter with grep/sed/awk. Never load full output.
 5. **No intermediate commits** — All changes committed once at the end via `/prizmkit-committer`.
 
-{{LOG_SIZE_AWARENESS}}
 ## Bug Fix Artifacts Directory
 
 ```
@@ -64,16 +61,7 @@ You are the **bug fix session agent**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}".
 └── fix-report.md        ← Final bug resolution report
 ```
 
-## Workflow Checkpoint System
-
-**Path**: `{{CHECKPOINT_PATH}}`
-
-**Rules**:
-1. **Before each step**: Read `workflow-checkpoint.json`, verify the previous step is `"completed"`. If not, complete it first.
-2. **Starting a step**: Update to `status: "in_progress"`.
-3. **After step completes**: Update to `status: "completed"`.
-4. **On failure**: Set to `status: "failed"` and continue if possible.
-5. **On resume**: Skip `"completed"` steps. Start from first `"pending"` or `"in_progress"` step.
+{{CHECKPOINT_SYSTEM}}
 
 ---
 
@@ -82,7 +70,7 @@ You are the **bug fix session agent**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}".
 ### Phase 0: Initialize
 
 ```bash
-mkdir -p .prizmkit/bugfix/{{BUG_ID}}
+{{RUNTIME_HELPER_CMD}} artifact ensure-dir .prizmkit/bugfix/{{BUG_ID}}
 ```
 
 {{IF_BROWSER_INTERACTION}}
@@ -138,7 +126,7 @@ Run `/prizmkit-plan` with `artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/`:
 - The spec.md should capture: root cause, impact scope, behavior that must be preserved
 - The plan.md Tasks section **MUST start with a reproduction test task** — a test that FAILS with current code (RED state), proving the bug exists
 - Subsequent tasks implement the minimal fix to make the test pass (GREEN state)
-- Resolve any `[NEEDS CLARIFICATION]` markers autonomously — do NOT pause
+- Resolve uncertain fix details autonomously from the bug report, failing behavior, existing code, and conservative existing-project patterns.
 
 {{IF_BROWSER_INTERACTION}}
 - **Browser Verification**: If the bug is UI-reproducible, plan.md should reference the Browser Verification Protocol above instead of redefining browser steps.
@@ -198,7 +186,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:
 ```bash
-grep -q "## Verdict" .prizmkit/bugfix/{{BUG_ID}}/review-report.md && echo "GATE:PASS" || echo "GATE:MISSING"
+{{RUNTIME_HELPER_CMD}} text contains .prizmkit/bugfix/{{BUG_ID}}/review-report.md --pattern "## Verdict"
 ```
 If GATE:MISSING:
 - Do not re-run `/prizmkit-code-review` in an unbounded report-repair loop.

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

@@ -61,9 +61,6 @@ You are the **refactor session orchestrator**. Execute Refactor {{REFACTOR_ID}}:
 
 {{GLOBAL_CONTEXT}}
 
-### Project Conventions
-
-> Read {{PLATFORM_CONVENTIONS}} for project-level coding standards, architecture decisions, and development rules.
 
 ## Refactor Artifacts Directory
 
@@ -78,7 +75,6 @@ You are the **refactor session orchestrator**. Execute Refactor {{REFACTOR_ID}}:
 
 ## Execution Instructions
 
-{{LOG_SIZE_AWARENESS}}
 **YOU are the orchestrator. Execute each phase by spawning the appropriate team agent with run_in_background=false.**
 
 **Agent spawn failure policy (all Agent tool calls)**:
@@ -88,15 +84,7 @@ You are the **refactor session orchestrator**. Execute Refactor {{REFACTOR_ID}}:
 - Any recovery exception must be recorded in the required report or session status so downstream runs know the normal team path was unavailable.
 - Apply the same cap to any re-spawn for report repair or resume prompts; do not burn multiple minutes on identical team/config/lock failures.
 
-## Workflow Checkpoint System
-
-A checkpoint file tracks your progress through this workflow:
-
-**Path**: `{{CHECKPOINT_PATH}}`
-
-**How to use**:
-1. **Before each step**: Read `workflow-checkpoint.json`, verify the previous step has `status: "completed"` or `status: "skipped"`. If not, complete it first.
-2. **After completing a step**: Update the step's `status` to `"completed"` in `workflow-checkpoint.json`.
+{{CHECKPOINT_SYSTEM}}
 
 ### Step 1: Initialize
 
@@ -108,7 +96,7 @@ Reference `{{TEAM_CONFIG_PATH}}` for agent definitions:
 
 Create refactor artifacts directory:
 ```bash
-mkdir -p .prizmkit/refactor/{{REFACTOR_ID}}
+{{RUNTIME_HELPER_CMD}} artifact ensure-dir .prizmkit/refactor/{{REFACTOR_ID}}
 ```
 
 ### Step 2: Pipeline Phases
@@ -129,7 +117,7 @@ Run `/prizmkit-plan` with `artifact_dir=.prizmkit/refactor/{{REFACTOR_ID}}/`:
   - Every task ends with "run test suite to verify behavior preserved"
   - Rollback strategy
 
-Resolve any `[NEEDS CLARIFICATION]` markers using the refactor description — do NOT pause for interactive input.
+Resolve uncertain refactor details from the refactor description, existing code, and conservative existing-project patterns.
 
 {{IF_BROWSER_INTERACTION}}
 
@@ -185,7 +173,7 @@ Evidence must cover affected UI render, primary user interactions, behavior-sens
 
 {{END_IF_BROWSER_INTERACTION}}
 
-  7. If the refactor involves multiple files: update durable checkpoints/artifacts at the midpoint, minimize output, and rely on runner continuation if context overflow occurs. In an interactive Claude Code session operated manually outside the headless pipeline, `/compact` may be used as an optional convenience only.
+  7. If the refactor involves multiple files: update durable checkpoints/artifacts at the midpoint, minimize output, and rely on runner continuation if context overflow occurs.
   8. After all tasks complete, run the full test suite one final time
   "
 - **Wait for Dev to return**
@@ -220,7 +208,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:
   ```bash
-  grep -q "## Verdict" .prizmkit/refactor/{{REFACTOR_ID}}/review-report.md && echo "GATE:PASS" || echo "GATE:MISSING"
+  {{RUNTIME_HELPER_CMD}} text contains .prizmkit/refactor/{{REFACTOR_ID}}/review-report.md --pattern "## Verdict"
   ```
   If GATE:MISSING:
   - Do not enter an unbounded report-repair loop and do not repeatedly re-spawn Reviewer.

package/bundled/dev-pipeline/templates/sections/checkpoint-system.md

@@ -4,63 +4,29 @@ A checkpoint file tracks your progress through this workflow:
 
 **Path**: `{{CHECKPOINT_PATH}}`
 
-### Rules
-
-1. **Before each skill**: Read `workflow-checkpoint.json`, verify the previous step has `status: "completed"` or `status: "skipped"`. If it is still `"pending"` or `"in_progress"`, you MUST complete it first before moving on.
-
-2. **Starting a skill**: Use the update script to set the current step to `status: "in_progress"`.
-
-3. **After each skill completes**: Use the update script to set the current step to `status: "completed"`.
-
-4. **On failure**: Use the update script to set the step to `status: "failed"` and continue to the next step if possible, or halt and write failure-log.md.
+### Checkpoint Update Helper
 
-5. **On session exit**: The checkpoint file reflects your actual progress. Do NOT manually set future steps to "completed".
-
-### Checkpoint Update Pattern
-
-**IMPORTANT: NEVER hand-write or edit `workflow-checkpoint.json` directly. Always use the update script.**
-
-After completing each skill, run:
+Use this helper to update checkpoint status. Do not hand-edit `workflow-checkpoint.json` directly.
 
 ```bash
-python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+{{CHECKPOINT_PYTHON_CMD}} \
   --checkpoint-path {{CHECKPOINT_PATH}} \
-  --step <SKILL_NAME> \
-  --status completed
+  --step <step-id-or-skill-name> \
+  --status <in_progress|completed|failed|skipped> \
+  --note "<optional note>"
 ```
 
-For example, after completing `prizmkit-implement`:
-```bash
-python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
-  --checkpoint-path {{CHECKPOINT_PATH}} \
-  --step prizmkit-implement \
-  --status completed
-```
+- Use the step `skill` value such as `prizmkit-implement`, or the step id such as `S04`.
+- Omit `--note` when there is no useful failure or handoff note.
 
-Before starting the next skill:
-```bash
-python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
-  --checkpoint-path {{CHECKPOINT_PATH}} \
-  --step <NEXT_SKILL_NAME> \
-  --status in_progress
-```
+### Rules
 
-On failure:
-```bash
-python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
-  --checkpoint-path {{CHECKPOINT_PATH}} \
-  --step <SKILL_NAME> \
-  --status failed \
-  --note "brief failure reason"
-```
+1. **Before each skill**: Read `workflow-checkpoint.json`, verify the previous step has `status: "completed"` or `status: "skipped"`. If it is still `"pending"` or `"in_progress"`, complete it first before moving on.
 
-The script outputs JSON: `{"ok": true, ...}` on success, `{"ok": false, "error": "..."}` on failure.
+2. **Starting a skill**: Use the checkpoint update helper to mark the current step as `status: "in_progress"`.
 
-### Resume Behavior
+3. **After each skill completes**: Use the checkpoint update helper to mark the current step as `status: "completed"`.
 
-**Checkpoint is the primary source of truth for resume.** On retry sessions:
+4. **On failure**: Use the checkpoint update helper to mark the step as `status: "failed"`, write `failure-log.md` with the reason, and continue only when the workflow rules allow it.
 
-1. Read `workflow-checkpoint.json` — steps already `"completed"` or `"skipped"` are skipped
-2. Start from the first `"pending"` or `"in_progress"` step
-3. If `failure-log.md` exists, read it for diagnostic context (why the previous session failed, what approach to try differently) — but do NOT use it to determine which step to resume from
-4. If `workflow-checkpoint.json` is missing or corrupted, fall back to `failure-log.md` + the resume phase as the legacy mechanism
+5. **On session exit**: The checkpoint file reflects your actual progress. Do NOT manually set future steps to `"completed"`.

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

@@ -6,18 +6,12 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 
 1. **context-snapshot.md is your single source of truth** — After it is built, 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. **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 /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 during the post-review gate, capture with `<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.
-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
+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.
+4. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
+5. **One task at a time** — Complete and test one task before starting the next.
+6. **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.
+7. **No intermediate commits** — Do NOT run `git add`/`git commit` during implementation phases. All changes are committed once at the end via `/prizmkit-committer`.
+8. **Capture test output once** — When running test suites during the post-review gate, capture with `<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.
 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`
@@ -32,4 +26,4 @@ You are running in **headless non-interactive mode** with a FINITE context windo
    - **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)
 10. **Build artifact hygiene** — After any build/compile command (`go build`, `npm run build`, `tsc`, etc.), ensure the output binary, build directory, generated bundle, or cache directory is ignored by git before the commit phase. Never commit compiled binaries, build output, or generated artifacts.
-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. Run `wc -l <file>` to get real line count, then `sed -n '<start>,<end>p' <file>` for exact range. 2 consecutive offset errors → STOP Reading that file. Never guess offsets — `grep -n '<anchor>'` first.

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

@@ -14,8 +14,4 @@ Use this material according to the following priority:
 ### App Global Context
 
 {{GLOBAL_CONTEXT}}
-
-### Project Conventions
-
-> Read {{PLATFORM_CONVENTIONS}} for project-level coding standards and architecture decisions.
 </feature-context>