prizmkit 1.1.107 → 1.1.108

package/bundled/dev-pipeline/scripts/generate-refactor-prompt.py

@@ -19,7 +19,7 @@ import os
 import re
 import sys
 
-from utils import enrich_global_context, load_json_file, read_platform_conventions, setup_logging
+from utils import enrich_global_context, load_json_file, read_checkpoint_system_section, resolve_prompt_platform, setup_logging
 from continuation import add_continuation_args, append_continuation_handoff, is_continuation
 
 
@@ -134,6 +134,7 @@ def parse_args():
     parser.add_argument("--resume-phase", required=True, help='Phase to resume from, or "null" for fresh start')
     parser.add_argument("--state-dir", default=None, help="State directory (default: .prizmkit/state/refactor)")
     parser.add_argument("--output", required=True, help="Output path for the rendered prompt")
+    parser.add_argument("--project-root", default=None, help="AI-visible project root used for rendered prompt paths")
     parser.add_argument("--template", default=None, help="Custom template path. Defaults to {script_dir}/../templates/refactor-bootstrap-prompt.md")
     parser.add_argument("--mode", default=None, help="Pipeline execution mode override: lite, standard, full")
     parser.add_argument("--critic", default=None, help="Enable critic agent: true/false")
@@ -167,19 +168,6 @@ def _parse_positive_int_env(name, default):
     return parsed
 
 
-def load_log_size_section(script_dir):
-    """Load passive checkpoint guidance for normal prompt generation."""
-    section_path = os.path.join(
-        script_dir, "..", "templates", "sections", "log-size-awareness.md",
-    )
-    if not os.path.isfile(section_path):
-        return ""
-
-    content, err = read_text_file(section_path)
-    if err:
-        return ""
-    return content
-
 def find_refactor(refactors, refactor_id):
     """Find and return the refactor dict matching the given ID."""
     for refactor in refactors:
@@ -396,22 +384,39 @@ def resolve_project_root(script_dir):
     return os.path.abspath(pipeline_parent)
 
 
+def _project_root_from_prizmkit_path(path):
+    """Infer project root from a path nested under .prizmkit/."""
+    if not path:
+        return ""
+    current = os.path.abspath(path)
+    if not os.path.isdir(current):
+        current = os.path.dirname(current)
+    while current and current != os.path.dirname(current):
+        if os.path.basename(current) == ".prizmkit":
+            return os.path.abspath(os.path.dirname(current))
+        current = os.path.dirname(current)
+    return ""
+
+
+def _args_project_root(args, script_dir):
+    """Return explicit AI-visible project root, plan-path root, or script-layout default."""
+    explicit = getattr(args, "project_root", None)
+    if explicit:
+        return os.path.abspath(explicit)
+    plan_root = _project_root_from_prizmkit_path(getattr(args, "refactor_list", ""))
+    if plan_root:
+        return plan_root
+    return resolve_project_root(script_dir)
+
+
 def build_replacements(args, refactor, refactors, global_context, script_dir):
     """Build the full dict of placeholder -> replacement value."""
-    project_root = resolve_project_root(script_dir)
+    project_root = _args_project_root(args, script_dir)
 
     # Platform-aware agent/team path resolution
-    platform = os.environ.get("PRIZMKIT_PLATFORM", "")
+    platform = resolve_prompt_platform(project_root)
     home_dir = os.path.expanduser("~")
 
-    if not platform:
-        if os.path.isdir(os.path.join(project_root, ".codex", "agents")):
-            platform = "codex"
-        elif os.path.isdir(os.path.join(project_root, ".claude", "agents")):
-            platform = "claude"
-        else:
-            platform = "codebuddy"
-
     if platform == "claude":
         agents_dir = os.path.join(project_root, ".claude", "agents")
         team_config_path = os.path.join(project_root, ".claude", "team-info.json")
@@ -428,10 +433,16 @@ def build_replacements(args, refactor, refactors, global_context, script_dir):
     dev_subagent = os.path.join(agents_dir, f"prizm-dev-team-dev{agent_ext}")
     reviewer_subagent = os.path.join(agents_dir, f"prizm-dev-team-reviewer{agent_ext}")
 
-    # Session status path
+    # Session status is controlled by the main runner state dir, even when
+    # rendered project paths are AI-visible worktree paths.
+    state_dir = (
+        os.path.abspath(args.state_dir)
+        if args.state_dir
+        else os.path.join(project_root, ".prizmkit", "state", "refactor")
+    )
     session_status_path = os.path.join(
-        project_root, ".prizmkit", "state", "refactor", args.refactor_id,
-        "sessions", args.session_id, "session-status.json"
+        state_dir, args.refactor_id, "sessions", args.session_id,
+        "session-status.json",
     )
 
     # Scope
@@ -493,7 +504,6 @@ def build_replacements(args, refactor, refactors, global_context, script_dir):
             browser_verify_steps = "   # (validate UI renders correctly and feature still works)"
 
     replacements = {
-        "{{LOG_SIZE_AWARENESS}}": load_log_size_section(script_dir),
         "{{SESSION_LOG_PATH}}": os.path.join(
             ".prizmkit", "state", "refactor", args.refactor_id,
             "sessions", args.session_id, "logs", "session.log",
@@ -527,8 +537,8 @@ def build_replacements(args, refactor, refactors, global_context, script_dir):
         "{{CHECKPOINT_PATH}}": os.path.join(
             ".prizmkit", "refactor", args.refactor_id, "workflow-checkpoint.json",
         ),
+        "{{CHECKPOINT_SYSTEM}}": read_checkpoint_system_section(script_dir),
         "{{TIMESTAMP}}": "",  # Placeholder — agent fills in timestamp
-        "{{PLATFORM_CONVENTIONS}}": read_platform_conventions(project_root),
         "{{BROWSER_ENABLED}}": "true" if browser_enabled else "false",
         "{{BROWSER_TOOL}}": browser_tool,
         "{{BROWSER_VERIFY_STEPS}}": browser_verify_steps,
@@ -696,9 +706,6 @@ def main():
 
     # Build replacements
     replacements = build_replacements(args, refactor, refactors, global_context, script_dir)
-    if is_continuation(args):
-        replacements["{{LOG_SIZE_AWARENESS}}"] = ""
-
     # Render the template
     rendered = render_template(template_content, replacements, args.resume_phase, refactor)
 
@@ -708,7 +715,7 @@ def main():
         emit_failure(err)
 
     # Generate checkpoint file
-    project_root = resolve_project_root(script_dir)
+    project_root = _args_project_root(args, script_dir)
     checkpoint_rel = os.path.join(
         ".prizmkit", "refactor", args.refactor_id, "workflow-checkpoint.json",
     )

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

@@ -79,6 +79,46 @@ def error_out(message, code=1):
     sys.exit(code)
 
 
+def read_checkpoint_system_section(script_dir):
+    """Read the shared checkpoint prompt section for feature/bugfix/refactor prompts."""
+    path = os.path.join(
+        os.path.abspath(script_dir), "..", "templates", "sections", "checkpoint-system.md"
+    )
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return f.read()
+    except IOError:
+        return """## Workflow Checkpoint System
+
+A checkpoint file tracks your progress through this workflow:
+
+**Path**: `{{CHECKPOINT_PATH}}`
+
+### Checkpoint Update Helper
+
+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-path {{CHECKPOINT_PATH}} \\
+  --step <step-id-or-skill-name> \\
+  --status <in_progress|completed|failed|skipped> \\
+  --note "<optional note>"
+```
+
+- 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.
+
+### 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"`, complete it first before moving on.
+2. **Starting a skill**: Use the checkpoint update helper to mark the current step as `status: "in_progress"`.
+3. **After each skill completes**: Use the checkpoint update helper to mark the current step as `status: "completed"`.
+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.
+5. **On session exit**: The checkpoint file reflects your actual progress. Do NOT manually set future steps to `"completed"`.
+"""
+
+
 def pad_right(text, width):
     """Pad text with spaces to fill width, accounting for ANSI escape codes."""
     i = 0
@@ -520,6 +560,89 @@ 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
+
+    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."
+    )
+
 def read_platform_conventions(project_root):
     """Resolve the platform-specific project conventions file.
 

package/bundled/dev-pipeline/templates/agent-prompts/critic-plan-challenge.md

@@ -1,7 +1,8 @@
 "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 project context, 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')."

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

@@ -44,7 +44,7 @@ Infer what needs to be done from the feature context above and follow the standa
 - Do NOT push to remote — the user will push manually.
 - Write all artifacts to `.prizmkit/specs/{{FEATURE_SLUG}}/`.
 - If a step fails after 3 attempts, write a status report and stop.
-- **Anti re-read**: once you read a file into context, do NOT read it again — use `grep -n`/`sed -n` for specific lines. 3 full Reads of same file → report BLOCKED.
+- **Never re-read unmodified files**: once you 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`/`sed -n` for specific lines. Before issuing a Read, ask: "Have I read this file before, and has it changed since?" If no — do NOT read it. Subagents (Critic, Reviewer) must rely on context-snapshot.md rather than re-reading files the orchestrator already read.
 - **Read offset safety**: if Read returns "shorter than offset"/"empty" — run `wc -l` then `sed -n`, do NOT retry same offset.
 - **Hard Round Cap**: after 6 total test-fix rounds, STOP trial-and-error. Switch to read-once-then-rewrite. Do NOT exceed 7 rounds.
 - **Layered test**: debug with single-file tests, only run full suite as gate when single-file is green.

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

@@ -46,21 +46,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 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 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.
 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.
-8. **Scaffold / generated file awareness** — Files created by scaffolding tools (`npm init`, `npx create-*`, etc.) are boilerplate. Tag them, record in context-snapshot.md, and NEVER re-read them. If you need to modify one, edit directly without reading first.
 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.
 
 ---
 
-{{LOG_SIZE_AWARENESS}}
----
-
 ## PrizmKit Directory Convention
 
 ```
@@ -114,7 +111,7 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
 
 If plan.md missing, run `/prizmkit-plan` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to generate `plan.md`:
 - The plan.md should include: key components, data flow, files to create/modify, and a Tasks section with `[ ]` checkboxes (each task = one implementable unit). Keep under 80 lines.
-- Resolve any `[NEEDS CLARIFICATION]` markers using the feature description — do NOT pause for interactive input.
+- Resolve uncertain requirements from the feature description, existing code, and conservative existing-project patterns.
 
 **Database Design Gate** (if feature involves data persistence — new tables, schema changes, new entities):
 Before proceeding past CP-1:
@@ -178,7 +175,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
+mkdir -p .prizmkit/specs/{{FEATURE_SLUG}}
+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.

package/bundled/dev-pipeline/templates/bootstrap-tier2.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 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. **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.
-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
 
 ```
@@ -99,13 +96,6 @@ If any agent times out:
 ### Phase 0: SKIP (already initialized)
 {{END_IF_INIT_DONE}}
 
-### Phase 0.5: 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`.
-
-Do not run tests in this phase. Test execution happens after code review in the scoped PrizmKit Test gate.
-
-> **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.
 
 ### Phase 1: Build Context Snapshot (you, the orchestrator)
 
@@ -159,20 +149,20 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/plan.md 2>/dev/null
 
 If either missing, run `/prizmkit-plan` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to generate missing files:
 - `plan.md`: architecture — components, interfaces, data flow, files to create/modify, testing approach, and a Tasks section with `[ ]` checkboxes ordered by dependency
-- Resolve any `[NEEDS CLARIFICATION]` markers using the feature description — do NOT pause for interactive input.
+- Resolve uncertain requirements from the feature description, existing code, and conservative existing-project patterns.
 
 **Database Design Gate** (if feature involves data persistence — new tables, schema changes, new entities):
 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**: plan.md exists with Tasks section.
 
 ### Phase 3: Analyze — Reviewer Subagent
 
-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.
 
@@ -201,7 +191,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.
 
@@ -209,9 +199,10 @@ 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 project context, 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')."
 
 Wait for Critic to return.
@@ -222,15 +213,16 @@ Wait for Critic to return.
 
 **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:
 > "Read {{CRITIC_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
 > **MODE: Plan Challenge — Lens: Architecture & Scalability**
 > Focus on: architectural pattern fit, scalability implications, over-engineering risks, component boundary design.
 > 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.
+> 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.
 > 4. Challenge plan.md through your architecture lens.
 > Write `.prizmkit/specs/{{FEATURE_SLUG}}/challenge-report-A.md`."
 
@@ -239,8 +231,9 @@ Critic-B prompt:
 > **MODE: Plan Challenge — Lens: Data Model & Edge Cases**
 > Focus on: data model design fit, entity relationships, edge cases in business logic, missing boundary conditions.
 > 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.
+> 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.
 > 4. Challenge plan.md through your data/edge-case lens.
 > Write `.prizmkit/specs/{{FEATURE_SLUG}}/challenge-report-B.md`."
 
@@ -249,8 +242,9 @@ Critic-C prompt:
 > **MODE: Plan Challenge — Lens: Security & Performance**
 > Focus on: security attack surface, authentication/authorization gaps, performance bottlenecks, resource leaks.
 > 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.
+> 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.
 > 4. Challenge plan.md through your security/performance lens.
 > Write `.prizmkit/specs/{{FEATURE_SLUG}}/challenge-report-C.md`."
 
@@ -309,15 +303,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.
@@ -347,7 +332,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
+mkdir -p .prizmkit/specs/{{FEATURE_SLUG}}
+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.