prizmkit 1.0.35 → 1.0.45

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

@@ -83,7 +83,7 @@ If MISSING — build it now:
    - **Section 1 — Feature Brief**: feature description + acceptance criteria (copy from above)
    - **Section 2 — Project Structure**: relevant `ls src/` output
    - **Section 3 — Prizm Context**: full content of root.prizm and relevant L1/L2 docs
-   - **Section 4 — Existing Source Files**: full content of each related file as code block
+   - **Section 4 — Existing Source Files**: **full verbatim content** of each related file in fenced code blocks (with `### path/to/file` heading and line count). Include ALL files needed for implementation and review — downstream subagents read this section instead of re-reading individual source files
    - **Section 5 — Existing Tests**: full content of related test files as code blocks
 
 ### Phase 2: Plan & Tasks (you, the orchestrator)
@@ -156,15 +156,9 @@ Stage any `.prizm-docs/` changes produced: `git add .prizm-docs/`
 ### Phase 5: Commit
 
 - Run `/prizmkit-summarize` → archive to REGISTRY.md
-- Mark feature complete:
-  ```bash
-  python3 {{VALIDATOR_SCRIPTS_DIR}}/update-feature-status.py \
-    --feature-list "{{FEATURE_LIST_PATH}}" \
-    --state-dir "{{PROJECT_ROOT}}/dev-pipeline/state" \
-    --feature-id "{{FEATURE_ID}}" --session-id "{{SESSION_ID}}" --action complete
-  ```
 - Run `/prizmkit-committer` → `feat({{FEATURE_ID}}): {{FEATURE_TITLE}}`, do NOT push
 - MANDATORY: commit must be done via `/prizmkit-committer` skill. Do NOT run manual `git add`/`git commit` as a substitute.
+- Do NOT run `update-feature-status.py` here — the pipeline runner handles feature-list.json updates automatically after session exit.
 
 ---
 

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

@@ -13,7 +13,7 @@ You are the **session orchestrator**. Implement Feature {{FEATURE_ID}}: "{{FEATU
 
 **CRITICAL**: You MUST NOT exit until ALL work is complete and session-status.json is written. When you spawn subagents, wait for each to finish (run_in_background=false). Do NOT spawn agents in background and exit — that kills the session.
 
-**Tier 3 — Full Team**: PM + Dev + Reviewer agents spawned directly via Task tool. Full 7-phase pipeline.
+**Tier 3 — Full Team**: Dev + Reviewer agents spawned directly via Task tool. Full 7-phase pipeline.
 
 ### Feature Description
 
@@ -68,16 +68,15 @@ LLM context is frozen at prompt time. Modifying a skill source file during this
 ## PrizmKit Directory Convention
 
 ```
-.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md  ← PM writes, all agents read
+.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md  ← orchestrator writes, all subagents read
 .prizmkit/specs/{{FEATURE_SLUG}}/spec.md
 .prizmkit/specs/{{FEATURE_SLUG}}/plan.md              ← includes Tasks section
 .prizmkit/specs/REGISTRY.md
 ```
 
-**`context-snapshot.md`** is the shared knowledge base. PM writes it once; Dev and Reviewer read it instead of re-scanning source files. This eliminates redundant I/O across all agents.
+**`context-snapshot.md`** is the shared knowledge base. Orchestrator writes it once; Dev and Reviewer read it instead of re-scanning source files. This eliminates redundant I/O across all agents.
 
 ### Agent Files
-- PM Agent: `{{PM_SUBAGENT_PATH}}`
 - Dev Agent: `{{DEV_SUBAGENT_PATH}}`
 - Reviewer Agent: `{{REVIEWER_SUBAGENT_PATH}}`
 
@@ -129,7 +128,6 @@ No TeamCreate required. Agents are spawned directly via the `Task` tool using `s
    `ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null`
 
 Agent files are at:
-- PM: `{{PM_SUBAGENT_PATH}}`
 - Dev: `{{DEV_SUBAGENT_PATH}}`
 - Reviewer: `{{REVIEWER_SUBAGENT_PATH}}`
 
@@ -144,7 +142,7 @@ python3 {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEAT
 After team setup: check `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — if exists, all agents MUST use it. Read existing artifacts and resume from Phase {{RESUME_PHASE}}.
 {{END_IF_RESUME}}
 
-### Phase 1-2: Specify + Plan — PM Agent
+### Phase 1-2: Specify + Plan — Orchestrator (you)
 
 Check existing artifacts first:
 ```bash
@@ -152,40 +150,44 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
 ```
 
 - Both (spec.md, plan.md) exist → **SKIP to CP-1**
-- `context-snapshot.md` exists → PM reads it instead of re-scanning source files
-- Some missing → PM generates only missing files
+- `context-snapshot.md` exists → use it directly, skip Phase 1
+- Some missing → generate only missing files
 
-Before spawning PM, check whether feature code already exists in the project:
+Before planning, check whether feature code already exists in the project:
 ```bash
 grep -r "{{FEATURE_SLUG}}" src/ --include="*.js" --include="*.ts" -l 2>/dev/null | head -20
 ```
 
-Record result as `EXISTING_CODE` (list of files, or empty). Pass this to PM prompt below.
+Record result as `EXISTING_CODE` (list of files, or empty).
 
-Spawn PM agent (Task tool, subagent_type="prizm-dev-team-pm", run_in_background=false).
+If `EXISTING_CODE` is non-empty: your spec/plan/tasks must reflect this existing implementation — document what exists, identify gaps, do NOT re-implement what is already done.
 
-**Construct prompt dynamically** — always prefix with:
-> "Read {{PM_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}), complete the following IN THIS SINGLE SESSION — do NOT exit until ALL listed steps are done and files are written to disk:"
+**Step A — Build Context Snapshot** (skip if `context-snapshot.md` already exists):
 
-If `EXISTING_CODE` is non-empty, append to prefix:
-> "NOTE: The following files related to this feature already exist in the codebase: `<EXISTING_CODE list>`. Your spec/plan/tasks must reflect this existing implementation — document what exists, identify gaps, do NOT re-implement what is already done."
+1. Read `.prizm-docs/root.prizm` and relevant L1/L2 prizm docs
+2. Scan `src/` for files related to this feature; read each one
+3. Write `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`:
+   - **Section 1 — Feature Brief**: feature description + acceptance criteria (copy from above)
+   - **Section 2 — Project Structure**: relevant `ls src/` output
+   - **Section 3 — Prizm Context**: full content of root.prizm and relevant L1/L2 docs
+   - **Section 4 — Existing Source Files**: **full verbatim content** of each related file in fenced code blocks (with `### path/to/file` heading and line count). Include ALL files needed for implementation and review — downstream subagents read this section instead of re-reading individual source files
+   - **Section 5 — Existing Tests**: full content of related test files as code blocks
+4. Confirm: `ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`
 
-**Step A — Build Context Snapshot** (include only if `context-snapshot.md` does NOT exist):
-> "Step A: Write `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`. This is the team knowledge base — complete it before anything else. Include:
-> - Section 1 'Feature Brief': feature description and acceptance criteria
-> - Section 2 'Project Structure': output of `ls src/` and relevant subdirectories
-> - Section 3 'Prizm Context': full content of `.prizm-docs/root.prizm` and relevant L1/L2 docs
-> - Section 4 'Existing Source Files': full content of every related source file as a code block
-> - Section 5 'Existing Tests': full content of related test files as code blocks
-> Confirm with `ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`."
+**After Step A, do NOT re-read any original source files** — use context-snapshot.md for all subsequent work.
 
-**Step B — Planning Artifacts** (include only missing files):
-- spec.md missing: "Run prizmkit-specify → generate spec.md. Resolve any `[NEEDS CLARIFICATION]` markers using the feature description — do NOT pause for interactive input."
-- plan.md missing: "Run prizmkit-plan → generate plan.md (architecture, components, interface design, data model, testing strategy, risk assessment, and Tasks section with `[ ]` checkboxes)"
+**Step B — Planning Artifacts** (generate only missing files):
 
-> "All files go under `.prizmkit/specs/{{FEATURE_SLUG}}/`. Confirm each with `ls` after writing."
+```bash
+ls .prizmkit/specs/{{FEATURE_SLUG}}/spec.md .prizmkit/specs/{{FEATURE_SLUG}}/plan.md 2>/dev/null
+```
+
+- spec.md missing: Run `/prizmkit-specify` → generate spec.md. Resolve any `[NEEDS CLARIFICATION]` markers using the feature description — do NOT pause for interactive input.
+- plan.md missing: Run `/prizmkit-plan` → generate plan.md (architecture, components, interface design, data model, testing strategy, risk assessment, and Tasks section with `[ ]` checkboxes)
 
-Wait for PM to return. **CP-1**: Both files exist. If missing, diagnose from PM output — do NOT spawn another PM blindly.
+> All files go under `.prizmkit/specs/{{FEATURE_SLUG}}/`. Confirm each with `ls` after writing.
+
+**CP-1**: Both spec.md and plan.md exist.
 
 ### Phase 4: Analyze — Reviewer Agent
 
@@ -199,9 +201,7 @@ Prompt:
 > Report: CRITICAL, HIGH, MEDIUM issues found (or 'No issues found')."
 
 Wait for Reviewer to return.
-- If CRITICAL issues found: spawn PM to fix — use this prompt:
-  > "Read {{PM_SUBAGENT_PATH}}. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST for full project context. Do NOT re-read individual source files. Fix ONLY the following CRITICAL issues in spec.md/plan.md/tasks.md: `<list issues>`. Do NOT exit until all files are updated."
-  Then re-run analyze (max 1 round).
+- If CRITICAL issues found: fix them yourself — read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` for full project context. Fix ONLY the listed CRITICAL issues in spec.md/plan.md/tasks.md. Then re-run analyze (max 1 round).
 
 **CP-2**: No CRITICAL issues.
 
@@ -335,17 +335,11 @@ git log --oneline | grep "{{FEATURE_ID}}" | head -3
 - Stage any `.prizm-docs/` changes: `git add .prizm-docs/`
 - **Skip if this session is bug-fix-only**
 
-**7c.** Mark feature complete:
-```bash
-python3 {{VALIDATOR_SCRIPTS_DIR}}/update-feature-status.py \
-  --feature-list "{{FEATURE_LIST_PATH}}" \
-  --state-dir "{{PROJECT_ROOT}}/dev-pipeline/state" \
-  --feature-id "{{FEATURE_ID}}" --session-id "{{SESSION_ID}}" --action complete
-```
+**7c.** Run `/prizmkit-committer` → `feat({{FEATURE_ID}}): {{FEATURE_TITLE}}`, do NOT push
 
-**7d.** Run `/prizmkit-committer` → `feat({{FEATURE_ID}}): {{FEATURE_TITLE}}`, do NOT push
+**7d.** MANDATORY: commit must be done via `/prizmkit-committer` skill. Do NOT run manual `git add`/`git commit` as a substitute.
 
-**7e.** MANDATORY: commit must be done via `/prizmkit-committer` skill. Do NOT run manual `git add`/`git commit` as a substitute.
+**7e.** Do NOT run `update-feature-status.py` here — the pipeline runner handles feature-list.json updates automatically after session exit.
 
 ---
 
@@ -409,7 +403,6 @@ No team cleanup needed — agents were spawned directly without TeamCreate.
 | Feature Artifacts Dir | `.prizmkit/specs/{{FEATURE_SLUG}}/` |
 | Context Snapshot | `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` |
 | Team Config | `{{TEAM_CONFIG_PATH}}` |
-| PM Agent Def | {{PM_SUBAGENT_PATH}} |
 | Dev Agent Def | {{DEV_SUBAGENT_PATH}} |
 | Reviewer Agent Def | {{REVIEWER_SUBAGENT_PATH}} |
 | Session Status Output | {{SESSION_STATUS_PATH}} |
@@ -418,8 +411,8 @@ No team cleanup needed — agents were spawned directly without TeamCreate.
 
 ## Reminders
 
-- Tier 3: full team — PM (planning) → Dev (implementation) → Reviewer (review) — agents spawned directly via Task tool (no TeamCreate needed)
-- context-snapshot.md is the team knowledge base: PM writes it once, all agents read it
+- Tier 3: full team — Dev (implementation) → Reviewer (review) — agents spawned directly via Task tool (no TeamCreate needed)
+- context-snapshot.md is the team knowledge base: orchestrator writes it once, all agents read it
 - Do NOT use `run_in_background=true` when spawning agents
 - ALWAYS write session-status.json before exiting
 - Commit phase must use `/prizmkit-committer`; do NOT replace with manual git commit commands

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

@@ -18,7 +18,7 @@ You are the **bug fix session orchestrator**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}
 
 **CRITICAL SESSION LIFECYCLE RULE**: You MUST NOT exit until ALL work is complete and session-status.json is written. When you spawn subagents, you MUST **wait for each to finish** (run_in_background=false) before proceeding. Do NOT spawn an agent in the background and exit — that kills the session.
 
-**MANDATORY TEAM REQUIREMENT**: You MUST use the `prizm-dev-team` multi-agent team. This is NON-NEGOTIABLE. All implementation and review work MUST be performed by the appropriate team agents (Dev, Reviewer).
+**MANDATORY TEAM REQUIREMENT**: You MUST use the `prizm-dev-team` multi-agent team. This is NON-NEGOTIABLE. All implementation and review work MUST be performed by the appropriate team agents (Dev, Reviewer). You are the orchestrator — handle coordination, planning, and commit phases directly.
 
 **BUG FIX DOCUMENTATION POLICY**: Bug fixes MUST NOT be recorded as new documentation entries:
 - Do NOT run `/prizmkit-summarize` (no REGISTRY.md entries)

package/bundled/dev-pipeline/templates/session-status-schema.json

@@ -15,7 +15,7 @@
     },
     "status": {
       "type": "string",
-      "enum": ["success", "partial", "failed", "commit_missing", "docs_missing"]
+      "enum": ["success", "partial", "failed", "commit_missing", "docs_missing", "merge_conflict"]
     },
     "completed_phases": {
       "type": "array",

package/bundled/dev-pipeline/tests/test_check_session.py

@@ -114,6 +114,10 @@ class TestDetermineStatus:
         data = {"status": "docs_missing"}
         assert determine_status(data) == "docs_missing"
 
+    def test_merge_conflict(self):
+        data = {"status": "merge_conflict"}
+        assert determine_status(data) == "merge_conflict"
+
     def test_unknown_status(self):
         data = {"status": "something_weird"}
         assert determine_status(data) == "crashed"

package/bundled/dev-pipeline/tests/test_update_feature_status.py

@@ -36,6 +36,9 @@ class TestSessionStatusValues:
     def test_contains_docs_missing(self):
         assert "docs_missing" in ufs.SESSION_STATUS_VALUES
 
+    def test_contains_merge_conflict(self):
+        assert "merge_conflict" in ufs.SESSION_STATUS_VALUES
+
 
 class TestNowIso:
     def test_returns_valid_iso_format(self):
@@ -252,6 +255,73 @@ class TestActionUpdateDegradedStatuses:
         f1 = next(x for x in data["features"] if x["id"] == "F-001")
         assert f1["status"] == "failed"
 
+    def test_merge_conflict_updates_feature_state_without_cleanup(
+        self, feature_list_file, state_dir, monkeypatch, capsys
+    ):
+        """merge_conflict is treated like commit_missing: retryable, no artifact cleanup."""
+        called = {"cleanup": 0}
+
+        def _fake_cleanup(**_kwargs):
+            called["cleanup"] += 1
+            return []
+
+        monkeypatch.setattr(ufs, "cleanup_feature_artifacts", _fake_cleanup)
+
+        args = SimpleNamespace(
+            feature_id="F-001",
+            session_status="merge_conflict",
+            session_id="s-merge-conflict",
+            max_retries=3,
+            project_root=None,
+        )
+
+        ufs.action_update(args, feature_list_file, state_dir)
+        out = capsys.readouterr().out
+        summary = json.loads(out)
+
+        fs = ufs.load_feature_status(state_dir, "F-001")
+        assert fs["status"] == "merge_conflict"
+        assert fs["retry_count"] == 1
+        assert summary["new_status"] == "merge_conflict"
+        assert summary["degraded_reason"] == "merge_conflict"
+        assert summary["restart_policy"] == "finalization_retry"
+        assert called["cleanup"] == 0
+
+        with open(feature_list_file, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        f1 = next(x for x in data["features"] if x["id"] == "F-001")
+        assert f1["status"] == "merge_conflict"
+
+    def test_merge_conflict_reaches_failed_when_retry_exhausted(
+        self, feature_list_file, state_dir, monkeypatch, capsys
+    ):
+        """merge_conflict with max_retries=1 should fail the feature."""
+        called = {"cleanup": 0}
+
+        def _fake_cleanup(**_kwargs):
+            called["cleanup"] += 1
+            return []
+
+        monkeypatch.setattr(ufs, "cleanup_feature_artifacts", _fake_cleanup)
+
+        args = SimpleNamespace(
+            feature_id="F-001",
+            session_status="merge_conflict",
+            session_id="s-merge-conflict-fail",
+            max_retries=1,
+            project_root=None,
+        )
+
+        ufs.action_update(args, feature_list_file, state_dir)
+        out = capsys.readouterr().out
+        summary = json.loads(out)
+
+        fs = ufs.load_feature_status(state_dir, "F-001")
+        assert fs["status"] == "failed"
+        assert fs["retry_count"] == 1
+        assert summary["new_status"] == "failed"
+        assert called["cleanup"] == 0
+
 
 class TestActionStatusForDegradedStates:
     def test_status_output_contains_degraded_counters(self, feature_list_file, state_dir, capsys):

package/bundled/dev-pipeline/tests/test_worktree.py

@@ -0,0 +1,236 @@
+"""Tests for dev-pipeline/lib/worktree.sh.
+
+Uses subprocess to invoke the worktree functions in a real (temporary) git repo
+to verify create/merge/cleanup/prune lifecycle.
+"""
+
+import json
+import os
+import subprocess
+import pytest
+
+
+SCRIPT_DIR = os.path.join(os.path.dirname(__file__), "..")
+LIB_DIR = os.path.join(SCRIPT_DIR, "lib")
+
+
+def _run_worktree_script(script_body, env=None):
+    """Run a bash script that sources worktree.sh (with stub log functions), then executes body."""
+    # We define stub log functions instead of sourcing common.sh to avoid
+    # CLI/platform detection which requires cbc/claude in PATH.
+    worktree_sh_path = os.path.join(os.path.abspath(LIB_DIR), "worktree.sh")
+    full_script = "\n".join([
+        "#!/usr/bin/env bash",
+        "set -euo pipefail",
+        # Stub log functions (worktree.sh uses log_info, log_warn, log_error, log_success)
+        'log_info()    { echo "[INFO] $*"; }',
+        'log_warn()    { echo "[WARN] $*"; }',
+        'log_error()   { echo "[ERROR] $*"; }',
+        'log_success() { echo "[SUCCESS] $*"; }',
+        'source "%s"' % worktree_sh_path,
+        script_body,
+    ])
+    merged_env = dict(os.environ)
+    if env:
+        merged_env.update(env)
+    result = subprocess.run(
+        ["bash", "-c", full_script],
+        capture_output=True,
+        text=True,
+        env=merged_env,
+    )
+    return result
+
+
+def _init_git_repo(path):
+    """Initialize a bare-bones git repo with an initial commit on 'main' branch."""
+    subprocess.run(["git", "init", str(path)], capture_output=True, check=True)
+    subprocess.run(
+        ["git", "-C", str(path), "config", "user.email", "test@test.com"],
+        capture_output=True,
+        check=True,
+    )
+    subprocess.run(
+        ["git", "-C", str(path), "config", "user.name", "Test"],
+        capture_output=True,
+        check=True,
+    )
+    # Create an initial commit so we have a branch
+    readme = os.path.join(str(path), "README.md")
+    with open(readme, "w") as f:
+        f.write("# Test Repo\n")
+    subprocess.run(
+        ["git", "-C", str(path), "add", "."], capture_output=True, check=True
+    )
+    subprocess.run(
+        ["git", "-C", str(path), "commit", "-m", "Initial commit"],
+        capture_output=True,
+        check=True,
+    )
+    # Ensure the branch is named 'main' regardless of git defaults
+    subprocess.run(
+        ["git", "-C", str(path), "branch", "-M", "main"],
+        capture_output=True,
+        check=True,
+    )
+
+
+class TestWorktreeCreate:
+    def test_creates_worktree_and_branch(self, tmp_path):
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+        wt_base = tmp_path / "worktrees"
+
+        script = (
+            'worktree_create "{repo}" "{wt_base}" "test-session-001" "main"\n'
+            'echo "PATH=$_WORKTREE_PATH"\n'
+            'echo "BRANCH=$_WORKTREE_BRANCH"\n'
+        ).format(repo=repo, wt_base=wt_base)
+
+        result = _run_worktree_script(script)
+        assert result.returncode == 0, f"stderr: {result.stderr}"
+
+        lines = result.stdout.strip().split("\n")
+        path_line = [l for l in lines if l.startswith("PATH=")]
+        branch_line = [l for l in lines if l.startswith("BRANCH=")]
+
+        assert len(path_line) == 1
+        assert len(branch_line) == 1
+
+        wt_path = path_line[0].split("=", 1)[1]
+        wt_branch = branch_line[0].split("=", 1)[1]
+
+        assert os.path.isdir(wt_path)
+        assert wt_branch == "worktree/test-session-001"
+
+        # Verify git branch exists
+        branch_check = subprocess.run(
+            ["git", "-C", str(repo), "rev-parse", "--verify", wt_branch],
+            capture_output=True,
+        )
+        assert branch_check.returncode == 0
+
+    def test_fails_when_worktree_already_exists(self, tmp_path):
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+        wt_base = tmp_path / "worktrees"
+
+        # Create the worktree directory manually to trigger failure
+        wt_path = wt_base / "dup-session"
+        wt_path.mkdir(parents=True)
+
+        script = (
+            'worktree_create "{repo}" "{wt_base}" "dup-session" "main"\n'
+            'echo "RC=$?"\n'
+        ).format(repo=repo, wt_base=wt_base)
+
+        # Since set -e is on and worktree_create returns 1, the script exits with 1
+        result = _run_worktree_script(script)
+        assert result.returncode != 0 or "RC=1" in result.stdout
+
+
+class TestWorktreeMerge:
+    def test_merge_success(self, tmp_path):
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+        wt_base = tmp_path / "worktrees"
+
+        # Create worktree, add a file, commit, then merge
+        script = (
+            'worktree_create "{repo}" "{wt_base}" "merge-test" "main"\n'
+            'echo "hello" > "$_WORKTREE_PATH/newfile.txt"\n'
+            'git -C "$_WORKTREE_PATH" add newfile.txt\n'
+            'git -C "$_WORKTREE_PATH" commit -m "Add newfile"\n'
+            'worktree_merge "{repo}" "$_WORKTREE_BRANCH" "main" "F-001" "merge-test"\n'
+            'echo "MERGE=$_MERGE_RESULT"\n'
+        ).format(repo=repo, wt_base=wt_base)
+
+        result = _run_worktree_script(script)
+        assert result.returncode == 0, f"stderr: {result.stderr}"
+        assert "MERGE=success" in result.stdout
+
+        # Verify the file exists on main
+        assert os.path.isfile(str(repo / "newfile.txt"))
+
+    def test_merge_conflict(self, tmp_path):
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+        wt_base = tmp_path / "worktrees"
+
+        # Create worktree, modify README on both main and worktree to cause conflict
+        script = (
+            # Create worktree
+            'worktree_create "{repo}" "{wt_base}" "conflict-test" "main"\n'
+            # Modify file in worktree and commit
+            'echo "worktree change" > "$_WORKTREE_PATH/README.md"\n'
+            'git -C "$_WORKTREE_PATH" add README.md\n'
+            'git -C "$_WORKTREE_PATH" commit -m "Worktree change"\n'
+            # Modify same file in main and commit
+            'echo "main change" > "{repo}/README.md"\n'
+            'git -C "{repo}" add README.md\n'
+            'git -C "{repo}" commit -m "Main change"\n'
+            # Attempt merge (should conflict)
+            'worktree_merge "{repo}" "worktree/conflict-test" "main" "F-001" "conflict-test" || true\n'
+            'echo "MERGE=$_MERGE_RESULT"\n'
+        ).format(repo=repo, wt_base=wt_base)
+
+        result = _run_worktree_script(script)
+        # Script may exit non-zero due to merge conflict detection
+        assert "MERGE=conflict" in result.stdout
+
+
+class TestWorktreeCleanup:
+    def test_cleanup_removes_worktree_and_branch(self, tmp_path):
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+        wt_base = tmp_path / "worktrees"
+
+        script = (
+            'worktree_create "{repo}" "{wt_base}" "cleanup-test" "main"\n'
+            'local_path="$_WORKTREE_PATH"\n'
+            'local_branch="$_WORKTREE_BRANCH"\n'
+            'worktree_cleanup "{repo}" "$local_path" "$local_branch"\n'
+            '[ -d "$local_path" ] && echo "DIR_EXISTS" || echo "DIR_GONE"\n'
+            'git -C "{repo}" rev-parse --verify "$local_branch" 2>/dev/null && echo "BRANCH_EXISTS" || echo "BRANCH_GONE"\n'
+        ).format(repo=repo, wt_base=wt_base)
+
+        result = _run_worktree_script(script)
+        assert result.returncode == 0, f"stderr: {result.stderr}"
+        assert "DIR_GONE" in result.stdout
+        assert "BRANCH_GONE" in result.stdout
+
+    def test_cleanup_idempotent(self, tmp_path):
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+
+        # Call cleanup on non-existent worktree/branch
+        script = (
+            'worktree_cleanup "{repo}" "/nonexistent/path" "nonexistent-branch"\n'
+            'echo "OK"\n'
+        ).format(repo=repo)
+
+        result = _run_worktree_script(script)
+        assert result.returncode == 0
+        assert "OK" in result.stdout
+
+
+class TestWorktreePruneStale:
+    def test_prune_stale(self, tmp_path):
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+
+        script = (
+            'worktree_prune_stale "{repo}"\n'
+            'echo "OK"\n'
+        ).format(repo=repo)
+
+        result = _run_worktree_script(script)
+        assert result.returncode == 0
+        assert "OK" in result.stdout