prizmkit 1.0.34 → 1.0.45

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

@@ -0,0 +1,796 @@
+"""Integration tests for F-001 Git Worktree Automation.
+
+Covers all 6 user stories from spec.md:
+  US-1: Isolated Session Execution via Worktree
+  US-2: Auto-Merge on Success
+  US-3: Conflict Detection and Recording
+  US-4: Optional Auto-Push
+  US-5: Worktree Cleanup
+  US-6: Backward Compatibility Toggle
+
+These tests verify cross-module interactions between:
+  - lib/worktree.sh (worktree lifecycle functions)
+  - run.sh / run-bugfix.sh (integration hooks)
+  - scripts/check-session-status.py (merge_conflict status recognition)
+  - scripts/update-feature-status.py (merge_conflict state handling)
+  - scripts/update-bug-status.py (merge_conflict state handling)
+  - templates/session-status-schema.json (schema validity)
+"""
+
+import json
+import os
+import subprocess
+import sys
+import pytest
+
+
+SCRIPT_DIR = os.path.join(os.path.dirname(__file__), "..")
+LIB_DIR = os.path.join(SCRIPT_DIR, "lib")
+SCRIPTS_DIR = os.path.join(SCRIPT_DIR, "scripts")
+TEMPLATES_DIR = os.path.join(SCRIPT_DIR, "templates")
+
+
+# ======================================================================
+# Helpers
+# ======================================================================
+
+
+def _init_git_repo(path):
+    """Initialize a git repo with an initial commit on 'main'."""
+    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,
+    )
+    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,
+    )
+    subprocess.run(
+        ["git", "-C", str(path), "branch", "-M", "main"],
+        capture_output=True, check=True,
+    )
+
+
+def _run_worktree_script(script_body, env=None):
+    """Run a bash script with worktree.sh sourced."""
+    worktree_sh_path = os.path.join(os.path.abspath(LIB_DIR), "worktree.sh")
+    full_script = "\n".join([
+        "#!/usr/bin/env bash",
+        "set -euo pipefail",
+        '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)
+    return subprocess.run(
+        ["bash", "-c", full_script],
+        capture_output=True, text=True, env=merged_env,
+    )
+
+
+def _import_module(name, filename):
+    """Import a Python script as a module."""
+    import importlib.util
+    path = os.path.join(SCRIPTS_DIR, filename)
+    spec = importlib.util.spec_from_file_location(name, path)
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules[name] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+# Lazy imports of the Python modules under test
+_css = None
+_ufs = None
+_ubs = None
+
+
+def _get_check_session_module():
+    global _css
+    if _css is None:
+        _css = _import_module("check_session_status_integ", "check-session-status.py")
+    return _css
+
+
+def _get_update_feature_module():
+    global _ufs
+    if _ufs is None:
+        _ufs = _import_module("update_feature_status_integ", "update-feature-status.py")
+    return _ufs
+
+
+def _get_update_bug_module():
+    global _ubs
+    if _ubs is None:
+        _ubs = _import_module("update_bug_status_integ", "update-bug-status.py")
+    return _ubs
+
+
+# ======================================================================
+# US-1: Isolated Session Execution via Worktree
+# ======================================================================
+
+
+class TestUS1_IsolatedSessionExecution:
+    """US-1: Each AI session runs in a dedicated git worktree branch."""
+
+    def test_ac_1_1_worktree_created_at_deterministic_path(self, tmp_path):
+        """AC-1.1: Worktree created at <state-dir>/worktrees/<session-id>/."""
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+        wt_base = tmp_path / "state" / "worktrees"
+
+        script = (
+            'worktree_create "{repo}" "{wt_base}" "F-001-20260318120000" "main"\n'
+            'echo "PATH=$_WORKTREE_PATH"\n'
+        ).format(repo=repo, wt_base=wt_base)
+
+        result = _run_worktree_script(script)
+        assert result.returncode == 0
+
+        path_line = [l for l in result.stdout.strip().split("\n") if l.startswith("PATH=")]
+        assert len(path_line) == 1
+        wt_path = path_line[0].split("=", 1)[1]
+
+        # Deterministic path check
+        expected_path = str(wt_base / "F-001-20260318120000")
+        assert wt_path == expected_path
+        assert os.path.isdir(wt_path)
+
+    def test_ac_1_2_branch_naming_pattern(self, tmp_path):
+        """AC-1.2: Branch name follows 'worktree/<feature-id>-<timestamp>'."""
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+        wt_base = tmp_path / "worktrees"
+
+        script = (
+            'worktree_create "{repo}" "{wt_base}" "F-001-20260318120000" "main"\n'
+            'echo "BRANCH=$_WORKTREE_BRANCH"\n'
+        ).format(repo=repo, wt_base=wt_base)
+
+        result = _run_worktree_script(script)
+        assert result.returncode == 0
+
+        branch_line = [l for l in result.stdout.strip().split("\n") if l.startswith("BRANCH=")]
+        assert len(branch_line) == 1
+        branch = branch_line[0].split("=", 1)[1]
+        assert branch == "worktree/F-001-20260318120000"
+
+    def test_ac_1_3_cli_session_runs_in_worktree_directory(self, tmp_path):
+        """AC-1.3: AI CLI session's working directory is the worktree root.
+
+        Verify that spawn_and_wait_session changes directory to worktree path.
+        (We test the cd logic in worktree.sh rather than spawning an actual CLI.)
+        """
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+        wt_base = tmp_path / "worktrees"
+
+        # Create worktree, then verify pwd inside it
+        script = (
+            'worktree_create "{repo}" "{wt_base}" "cd-test" "main"\n'
+            'cd "$_WORKTREE_PATH"\n'
+            'pwd\n'
+        ).format(repo=repo, wt_base=wt_base)
+
+        result = _run_worktree_script(script)
+        assert result.returncode == 0
+        expected = str(wt_base / "cd-test")
+        # Resolve symlinks for macOS /private/tmp
+        actual_pwd = result.stdout.strip().split("\n")[-1]
+        assert os.path.realpath(actual_pwd) == os.path.realpath(expected)
+
+    def test_ac_1_4_worktree_created_from_current_head(self, tmp_path):
+        """AC-1.4: Worktree created from the current HEAD of main."""
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+
+        # Get main HEAD commit
+        main_head = subprocess.run(
+            ["git", "-C", str(repo), "rev-parse", "HEAD"],
+            capture_output=True, text=True, check=True,
+        ).stdout.strip()
+
+        wt_base = tmp_path / "worktrees"
+        script = (
+            'worktree_create "{repo}" "{wt_base}" "head-test" "main"\n'
+            'wt_head=$(git -C "$_WORKTREE_PATH" rev-parse HEAD)\n'
+            'echo "WT_HEAD=$wt_head"\n'
+        ).format(repo=repo, wt_base=wt_base)
+
+        result = _run_worktree_script(script)
+        assert result.returncode == 0
+        wt_head_line = [l for l in result.stdout.strip().split("\n") if l.startswith("WT_HEAD=")]
+        wt_head = wt_head_line[0].split("=", 1)[1]
+        assert wt_head == main_head
+
+
+# ======================================================================
+# US-2: Auto-Merge on Success
+# ======================================================================
+
+
+class TestUS2_AutoMergeOnSuccess:
+    """US-2: Successful sessions are auto-merged back into main."""
+
+    def test_ac_2_1_merge_no_ff_on_success(self, tmp_path):
+        """AC-2.1: On success, pipeline performs git merge --no-ff."""
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+        wt_base = tmp_path / "worktrees"
+
+        script = (
+            'worktree_create "{repo}" "{wt_base}" "merge-noff" "main"\n'
+            'echo "new content" > "$_WORKTREE_PATH/feature.txt"\n'
+            'git -C "$_WORKTREE_PATH" add feature.txt\n'
+            'git -C "$_WORKTREE_PATH" commit -m "Add feature"\n'
+            'worktree_merge "{repo}" "$_WORKTREE_BRANCH" "main" "F-001" "merge-noff"\n'
+            'echo "MERGE=$_MERGE_RESULT"\n'
+            # Verify it's a merge commit (has 2 parents)
+            'parents=$(git -C "{repo}" log -1 --format="%P" HEAD)\n'
+            'parent_count=$(echo "$parents" | wc -w | tr -d " ")\n'
+            'echo "PARENTS=$parent_count"\n'
+        ).format(repo=repo, wt_base=wt_base)
+
+        result = _run_worktree_script(script)
+        assert result.returncode == 0
+        assert "MERGE=success" in result.stdout
+        assert "PARENTS=2" in result.stdout
+
+    def test_ac_2_2_merge_commit_message_includes_ids(self, tmp_path):
+        """AC-2.2: Merge commit message includes feature/bug ID and session ID."""
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+        wt_base = tmp_path / "worktrees"
+
+        script = (
+            'worktree_create "{repo}" "{wt_base}" "msg-test" "main"\n'
+            'echo "x" > "$_WORKTREE_PATH/x.txt"\n'
+            'git -C "$_WORKTREE_PATH" add x.txt\n'
+            'git -C "$_WORKTREE_PATH" commit -m "Work"\n'
+            'worktree_merge "{repo}" "$_WORKTREE_BRANCH" "main" "F-001" "msg-test"\n'
+            'git -C "{repo}" log -1 --format="%s" HEAD\n'
+        ).format(repo=repo, wt_base=wt_base)
+
+        result = _run_worktree_script(script)
+        assert result.returncode == 0
+        lines = result.stdout.strip().split("\n")
+        # Last line should be the commit message
+        commit_msg = lines[-1]
+        assert "F-001" in commit_msg
+        assert "msg-test" in commit_msg
+
+    def test_ac_2_3_worktree_branch_deleted_after_successful_merge(self, tmp_path):
+        """AC-2.3: After merge, worktree branch and directory are deleted."""
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+        wt_base = tmp_path / "worktrees"
+
+        script = (
+            'worktree_create "{repo}" "{wt_base}" "del-test" "main"\n'
+            'local_path="$_WORKTREE_PATH"\n'
+            'local_branch="$_WORKTREE_BRANCH"\n'
+            'echo "y" > "$_WORKTREE_PATH/y.txt"\n'
+            'git -C "$_WORKTREE_PATH" add y.txt\n'
+            'git -C "$_WORKTREE_PATH" commit -m "Work"\n'
+            'worktree_merge "{repo}" "$local_branch" "main" "F-001" "del-test"\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
+        assert "DIR_GONE" in result.stdout
+        assert "BRANCH_GONE" in result.stdout
+
+
+# ======================================================================
+# US-3: Conflict Detection and Recording
+# ======================================================================
+
+
+class TestUS3_ConflictDetectionAndRecording:
+    """US-3: Merge conflicts detected and recorded as distinct status."""
+
+    def test_ac_3_1_merge_abort_on_conflict(self, tmp_path):
+        """AC-3.1: On conflict, merge is aborted (working tree left clean)."""
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+        wt_base = tmp_path / "worktrees"
+
+        script = (
+            'worktree_create "{repo}" "{wt_base}" "conflict-abort" "main"\n'
+            'echo "wt change" > "$_WORKTREE_PATH/README.md"\n'
+            'git -C "$_WORKTREE_PATH" add README.md\n'
+            'git -C "$_WORKTREE_PATH" commit -m "WT change"\n'
+            'echo "main change" > "{repo}/README.md"\n'
+            'git -C "{repo}" add README.md\n'
+            'git -C "{repo}" commit -m "Main change"\n'
+            'worktree_merge "{repo}" "worktree/conflict-abort" "main" "F-001" "conflict-abort" || true\n'
+            'echo "MERGE=$_MERGE_RESULT"\n'
+            # Verify working tree is clean after abort
+            'dirty=$(git -C "{repo}" status --porcelain)\n'
+            '[ -z "$dirty" ] && echo "CLEAN" || echo "DIRTY"\n'
+        ).format(repo=repo, wt_base=wt_base)
+
+        result = _run_worktree_script(script)
+        assert "MERGE=conflict" in result.stdout
+        assert "CLEAN" in result.stdout
+
+    def test_ac_3_2_session_status_set_to_merge_conflict(self):
+        """AC-3.2: merge_conflict recognized by check-session-status.py."""
+        css = _get_check_session_module()
+        data = {"status": "merge_conflict"}
+        assert css.determine_status(data) == "merge_conflict"
+
+    def test_ac_3_3_schema_includes_merge_conflict(self):
+        """AC-3.3: merge_conflict is in session-status-schema.json."""
+        schema_path = os.path.join(TEMPLATES_DIR, "session-status-schema.json")
+        with open(schema_path, "r", encoding="utf-8") as f:
+            schema = json.load(f)
+        status_enum = schema["properties"]["status"]["enum"]
+        assert "merge_conflict" in status_enum
+
+    def test_ac_3_4_feature_status_recognizes_merge_conflict(self, tmp_path):
+        """AC-3.4: update-feature-status.py treats merge_conflict as retryable."""
+        ufs = _get_update_feature_module()
+        assert "merge_conflict" in ufs.SESSION_STATUS_VALUES
+
+    def test_ac_3_4_bug_status_recognizes_merge_conflict(self):
+        """AC-3.4: update-bug-status.py treats merge_conflict as retryable."""
+        ubs = _get_update_bug_module()
+        assert "merge_conflict" in ubs.SESSION_STATUS_VALUES
+
+    def test_ac_3_5_worktree_preserved_on_conflict(self, tmp_path):
+        """AC-3.5: Worktree branch is preserved (not deleted) on merge conflict."""
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+        wt_base = tmp_path / "worktrees"
+
+        script = (
+            'worktree_create "{repo}" "{wt_base}" "preserve-test" "main"\n'
+            'echo "wt" > "$_WORKTREE_PATH/README.md"\n'
+            'git -C "$_WORKTREE_PATH" add README.md\n'
+            'git -C "$_WORKTREE_PATH" commit -m "WT"\n'
+            'echo "main" > "{repo}/README.md"\n'
+            'git -C "{repo}" add README.md\n'
+            'git -C "{repo}" commit -m "Main"\n'
+            'worktree_merge "{repo}" "worktree/preserve-test" "main" "F-001" "preserve-test" || true\n'
+            'echo "MERGE=$_MERGE_RESULT"\n'
+            # Do NOT call worktree_cleanup (simulating merge_conflict path)
+            '[ -d "$_WORKTREE_PATH" ] && echo "DIR_EXISTS" || echo "DIR_GONE"\n'
+            'git -C "{repo}" rev-parse --verify "worktree/preserve-test" 2>/dev/null && echo "BRANCH_EXISTS" || echo "BRANCH_GONE"\n'
+        ).format(repo=repo, wt_base=wt_base)
+
+        result = _run_worktree_script(script)
+        assert "MERGE=conflict" in result.stdout
+        assert "DIR_EXISTS" in result.stdout
+        assert "BRANCH_EXISTS" in result.stdout
+
+
+# ======================================================================
+# US-4: Optional Auto-Push
+# ======================================================================
+
+
+class TestUS4_OptionalAutoPush:
+    """US-4: Conflict-free merges optionally auto-push to remote."""
+
+    def test_ac_4_1_env_var_documentation_in_run_sh(self):
+        """AC-4.1: AUTO_PUSH env var is documented in run.sh header."""
+        run_sh_path = os.path.join(SCRIPT_DIR, "run.sh")
+        with open(run_sh_path, "r") as f:
+            header = f.read(3000)  # Read header section
+        assert "AUTO_PUSH" in header
+
+    def test_ac_4_2_auto_push_documented_in_run_bugfix_sh(self):
+        """AC-4.1 (bugfix): AUTO_PUSH documented in run-bugfix.sh header."""
+        run_bugfix_path = os.path.join(SCRIPT_DIR, "run-bugfix.sh")
+        with open(run_bugfix_path, "r") as f:
+            header = f.read(2000)
+        assert "AUTO_PUSH" in header
+
+    def test_ac_4_3_auto_push_defaults_to_0(self):
+        """AC-4.3: AUTO_PUSH defaults to 0 (disabled)."""
+        run_sh_path = os.path.join(SCRIPT_DIR, "run.sh")
+        with open(run_sh_path, "r") as f:
+            content = f.read()
+        assert "AUTO_PUSH=${AUTO_PUSH:-0}" in content
+
+    def test_ac_4_3_auto_push_defaults_to_0_bugfix(self):
+        """AC-4.3 (bugfix): AUTO_PUSH defaults to 0 in run-bugfix.sh."""
+        run_bugfix_path = os.path.join(SCRIPT_DIR, "run-bugfix.sh")
+        with open(run_bugfix_path, "r") as f:
+            content = f.read()
+        assert "AUTO_PUSH=${AUTO_PUSH:-0}" in content
+
+
+# ======================================================================
+# US-5: Worktree Cleanup
+# ======================================================================
+
+
+class TestUS5_WorktreeCleanup:
+    """US-5: Worktrees cleaned up after merge or failure."""
+
+    def test_ac_5_1_cleanup_after_successful_merge(self, tmp_path):
+        """AC-5.1: After successful merge, worktree removed via git worktree remove --force."""
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+        wt_base = tmp_path / "worktrees"
+
+        script = (
+            'worktree_create "{repo}" "{wt_base}" "cleanup-merge" "main"\n'
+            'echo "z" > "$_WORKTREE_PATH/z.txt"\n'
+            'git -C "$_WORKTREE_PATH" add z.txt\n'
+            'git -C "$_WORKTREE_PATH" commit -m "Add z"\n'
+            'local_path="$_WORKTREE_PATH"\n'
+            'local_branch="$_WORKTREE_BRANCH"\n'
+            'worktree_merge "{repo}" "$local_branch" "main" "F-001" "cleanup-merge"\n'
+            'worktree_cleanup "{repo}" "$local_path" "$local_branch"\n'
+            '[ -d "$local_path" ] && echo "DIR_EXISTS" || echo "DIR_GONE"\n'
+            # Verify no worktree entries remain
+            'wt_count=$(git -C "{repo}" worktree list | wc -l | tr -d " ")\n'
+            'echo "WT_COUNT=$wt_count"\n'
+        ).format(repo=repo, wt_base=wt_base)
+
+        result = _run_worktree_script(script)
+        assert result.returncode == 0
+        assert "DIR_GONE" in result.stdout
+        # Only the main worktree should remain
+        wt_line = [l for l in result.stdout.strip().split("\n") if l.startswith("WT_COUNT=")]
+        assert wt_line[0] == "WT_COUNT=1"
+
+    def test_ac_5_2_cleanup_after_failed_session(self, tmp_path):
+        """AC-5.2: After failed session, worktree is removed."""
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+        wt_base = tmp_path / "worktrees"
+
+        script = (
+            'worktree_create "{repo}" "{wt_base}" "fail-cleanup" "main"\n'
+            'local_path="$_WORKTREE_PATH"\n'
+            'local_branch="$_WORKTREE_BRANCH"\n'
+            # Simulate failure: no commit, just cleanup
+            'worktree_cleanup "{repo}" "$local_path" "$local_branch"\n'
+            '[ -d "$local_path" ] && echo "DIR_EXISTS" || echo "DIR_GONE"\n'
+        ).format(repo=repo, wt_base=wt_base)
+
+        result = _run_worktree_script(script)
+        assert result.returncode == 0
+        assert "DIR_GONE" in result.stdout
+
+    def test_ac_5_3_cleanup_trap_references_active_worktree_vars(self):
+        """AC-5.3: Cleanup trap in run.sh references _ACTIVE_WORKTREE_PATH."""
+        run_sh_path = os.path.join(SCRIPT_DIR, "run.sh")
+        with open(run_sh_path, "r") as f:
+            content = f.read()
+        # The cleanup function should reference active worktree
+        assert "_ACTIVE_WORKTREE_PATH" in content
+        assert "worktree_cleanup" in content
+
+    def test_ac_5_3_cleanup_trap_in_run_bugfix(self):
+        """AC-5.3 (bugfix): Cleanup trap in run-bugfix.sh references active worktree."""
+        path = os.path.join(SCRIPT_DIR, "run-bugfix.sh")
+        with open(path, "r") as f:
+            content = f.read()
+        assert "_ACTIVE_WORKTREE_PATH" in content
+        assert "worktree_cleanup" in content
+
+    def test_ac_5_4_conflict_preserves_worktree(self, tmp_path):
+        """AC-5.4: On merge_conflict, worktree is preserved."""
+        # Already covered by TestUS3 test_ac_3_5_worktree_preserved_on_conflict
+        # Additional: verify the logic in run.sh
+        run_sh_path = os.path.join(SCRIPT_DIR, "run.sh")
+        with open(run_sh_path, "r") as f:
+            content = f.read()
+        # After conflict, code should NOT call worktree_cleanup
+        # Instead it logs a message about preservation
+        assert "Worktree branch preserved for manual conflict resolution" in content
+
+
+# ======================================================================
+# US-6: Backward Compatibility Toggle
+# ======================================================================
+
+
+class TestUS6_BackwardCompatibilityToggle:
+    """US-6: USE_WORKTREE=0 disables worktree isolation."""
+
+    def test_ac_6_1_use_worktree_defaults_to_1_run_sh(self):
+        """AC-6.1: USE_WORKTREE defaults to 1 in run.sh."""
+        path = os.path.join(SCRIPT_DIR, "run.sh")
+        with open(path, "r") as f:
+            content = f.read()
+        assert "USE_WORKTREE=${USE_WORKTREE:-1}" in content
+
+    def test_ac_6_1_use_worktree_defaults_to_1_run_bugfix(self):
+        """AC-6.1: USE_WORKTREE defaults to 1 in run-bugfix.sh."""
+        path = os.path.join(SCRIPT_DIR, "run-bugfix.sh")
+        with open(path, "r") as f:
+            content = f.read()
+        assert "USE_WORKTREE=${USE_WORKTREE:-1}" in content
+
+    def test_ac_6_2_use_worktree_0_skips_worktree_creation(self):
+        """AC-6.2: USE_WORKTREE=0 makes pipeline behavior identical to no-worktree.
+
+        Verify the conditional guard exists in run.sh: the worktree code
+        is gated behind 'if [[ "$USE_WORKTREE" == "1" ]]'.
+        """
+        path = os.path.join(SCRIPT_DIR, "run.sh")
+        with open(path, "r") as f:
+            content = f.read()
+        assert '"$USE_WORKTREE" == "1"' in content
+
+    def test_ac_6_3_env_var_documented_in_header_run_sh(self):
+        """AC-6.3: USE_WORKTREE documented in run.sh header."""
+        path = os.path.join(SCRIPT_DIR, "run.sh")
+        with open(path, "r") as f:
+            header = f.read(3000)
+        assert "USE_WORKTREE" in header
+
+    def test_ac_6_3_env_var_documented_in_header_run_bugfix(self):
+        """AC-6.3: USE_WORKTREE documented in run-bugfix.sh header."""
+        path = os.path.join(SCRIPT_DIR, "run-bugfix.sh")
+        with open(path, "r") as f:
+            header = f.read(2000)
+        assert "USE_WORKTREE" in header
+
+    def test_ac_6_4_launch_daemon_documents_worktree_env(self):
+        """AC-6.4: launch-daemon.sh documents USE_WORKTREE via --env."""
+        path = os.path.join(SCRIPT_DIR, "launch-daemon.sh")
+        with open(path, "r") as f:
+            content = f.read()
+        assert "USE_WORKTREE" in content
+        assert "AUTO_PUSH" in content
+
+    def test_ac_6_4_launch_bugfix_daemon_documents_worktree_env(self):
+        """AC-6.4: launch-bugfix-daemon.sh documents USE_WORKTREE via --env."""
+        path = os.path.join(SCRIPT_DIR, "launch-bugfix-daemon.sh")
+        with open(path, "r") as f:
+            content = f.read()
+        assert "USE_WORKTREE" in content
+        assert "AUTO_PUSH" in content
+
+
+# ======================================================================
+# Cross-Module Data Flow Tests
+# ======================================================================
+
+
+class TestCrossModuleDataFlow:
+    """Verify end-to-end data flow across worktree.sh, status scripts, and schema."""
+
+    def test_full_lifecycle_success_path(self, tmp_path):
+        """E2E: create worktree → work → commit → merge → cleanup."""
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+        wt_base = tmp_path / "worktrees"
+
+        script = (
+            'worktree_create "{repo}" "{wt_base}" "e2e-success" "main"\n'
+            'echo "feature code" > "$_WORKTREE_PATH/feature.py"\n'
+            'git -C "$_WORKTREE_PATH" add feature.py\n'
+            'git -C "$_WORKTREE_PATH" commit -m "Implement feature"\n'
+            'local_path="$_WORKTREE_PATH"\n'
+            'local_branch="$_WORKTREE_BRANCH"\n'
+            'worktree_merge "{repo}" "$local_branch" "main" "F-001" "e2e-success"\n'
+            'worktree_cleanup "{repo}" "$local_path" "$local_branch"\n'
+            # Verify feature.py is on main
+            '[ -f "{repo}/feature.py" ] && echo "FILE_ON_MAIN" || echo "FILE_MISSING"\n'
+            # Verify worktree is gone
+            '[ -d "$local_path" ] && echo "WT_EXISTS" || echo "WT_GONE"\n'
+            # Verify branch is gone
+            'git -C "{repo}" rev-parse --verify "$local_branch" 2>/dev/null && echo "BR_EXISTS" || echo "BR_GONE"\n'
+        ).format(repo=repo, wt_base=wt_base)
+
+        result = _run_worktree_script(script)
+        assert result.returncode == 0
+        assert "FILE_ON_MAIN" in result.stdout
+        assert "WT_GONE" in result.stdout
+        assert "BR_GONE" in result.stdout
+
+    def test_full_lifecycle_conflict_path(self, tmp_path):
+        """E2E: create worktree → conflicting changes → merge fails → worktree preserved."""
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+        wt_base = tmp_path / "worktrees"
+
+        script = (
+            'worktree_create "{repo}" "{wt_base}" "e2e-conflict" "main"\n'
+            'echo "wt content" > "$_WORKTREE_PATH/README.md"\n'
+            'git -C "$_WORKTREE_PATH" add README.md\n'
+            'git -C "$_WORKTREE_PATH" commit -m "WT edit"\n'
+            'echo "main content" > "{repo}/README.md"\n'
+            'git -C "{repo}" add README.md\n'
+            'git -C "{repo}" commit -m "Main edit"\n'
+            'worktree_merge "{repo}" "worktree/e2e-conflict" "main" "F-001" "e2e-conflict" || true\n'
+            'echo "MERGE=$_MERGE_RESULT"\n'
+            # Worktree should be preserved
+            '[ -d "$_WORKTREE_PATH" ] && echo "WT_PRESERVED" || echo "WT_GONE"\n'
+        ).format(repo=repo, wt_base=wt_base)
+
+        result = _run_worktree_script(script)
+        assert "MERGE=conflict" in result.stdout
+        assert "WT_PRESERVED" in result.stdout
+
+    def test_merge_conflict_propagates_through_status_pipeline(
+        self, feature_list_file, state_dir, monkeypatch, capsys
+    ):
+        """E2E: merge_conflict flows from worktree → update-feature-status → state.
+
+        Verifies the cross-module integration:
+        1. merge_conflict is in SESSION_STATUS_VALUES
+        2. action_update handles it as retryable without cleanup
+        3. Status persists correctly in state
+        """
+        from types import SimpleNamespace
+        ufs = _get_update_feature_module()
+
+        called = {"cleanup": 0}
+        def _fake_cleanup(**_kw):
+            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-e2e",
+            max_retries=3,
+            project_root=None,
+        )
+        ufs.action_update(args, feature_list_file, state_dir)
+        out = capsys.readouterr().out
+        summary = json.loads(out)
+
+        assert summary["new_status"] == "merge_conflict"
+        assert summary["degraded_reason"] == "merge_conflict"
+        assert summary["restart_policy"] == "finalization_retry"
+        assert called["cleanup"] == 0
+
+    def test_merge_conflict_in_bug_pipeline(
+        self, bug_list_file, bugfix_state_dir, capsys
+    ):
+        """E2E: merge_conflict flows through update-bug-status.py."""
+        from types import SimpleNamespace
+        ubs = _get_update_bug_module()
+
+        args = SimpleNamespace(
+            bug_id="B-001",
+            session_status="merge_conflict",
+            session_id="s-bug-merge-conflict",
+            max_retries=3,
+            project_root=None,
+        )
+        ubs.action_update(args, bug_list_file, bugfix_state_dir)
+        out = capsys.readouterr().out
+        summary = json.loads(out)
+
+        assert summary["new_status"] == "merge_conflict"
+        assert summary["degraded_reason"] == "merge_conflict"
+        assert summary["restart_policy"] == "finalization_retry"
+
+
+# ======================================================================
+# Edge Cases and Boundary Conditions
+# ======================================================================
+
+
+class TestEdgeCases:
+    """Boundary conditions and error paths."""
+
+    def test_worktree_create_fails_on_duplicate_branch(self, tmp_path):
+        """Edge: Creating worktree with existing branch name fails gracefully."""
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+        wt_base = tmp_path / "worktrees"
+
+        # Create a branch manually
+        subprocess.run(
+            ["git", "-C", str(repo), "branch", "worktree/dup-branch"],
+            capture_output=True, check=True,
+        )
+
+        script = (
+            'worktree_create "{repo}" "{wt_base}" "dup-branch" "main" || echo "CREATE_FAILED"\n'
+        ).format(repo=repo, wt_base=wt_base)
+
+        result = _run_worktree_script(script)
+        assert "CREATE_FAILED" in result.stdout or result.returncode != 0
+
+    def test_worktree_cleanup_is_idempotent(self, tmp_path):
+        """Edge: Double cleanup doesn't error."""
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        _init_git_repo(repo)
+
+        script = (
+            'worktree_cleanup "{repo}" "/nonexistent/path" "nonexistent-branch"\n'
+            '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
+
+    def test_prune_stale_at_startup(self):
+        """Edge: Verify worktree_prune_stale is called at startup in main()."""
+        path = os.path.join(SCRIPT_DIR, "run.sh")
+        with open(path, "r") as f:
+            content = f.read()
+        # In main() there should be a prune call
+        assert "worktree_prune_stale" in content
+
+    def test_merge_conflict_retry_exhaustion_leads_to_failed(
+        self, feature_list_file, state_dir, monkeypatch, capsys
+    ):
+        """Edge: merge_conflict with max_retries=1 should fail the feature."""
+        from types import SimpleNamespace
+        ufs = _get_update_feature_module()
+
+        monkeypatch.setattr(ufs, "cleanup_feature_artifacts", lambda **_: [])
+
+        args = SimpleNamespace(
+            feature_id="F-001",
+            session_status="merge_conflict",
+            session_id="s-exhaust",
+            max_retries=1,
+            project_root=None,
+        )
+        ufs.action_update(args, feature_list_file, state_dir)
+        out = capsys.readouterr().out
+        summary = json.loads(out)
+
+        assert summary["new_status"] == "failed"
+        assert summary["retry_count"] == 1
+
+    def test_schema_validates_with_merge_conflict_status(self, tmp_path):
+        """Edge: A session-status.json with merge_conflict passes schema validation."""
+        schema_path = os.path.join(TEMPLATES_DIR, "session-status-schema.json")
+        with open(schema_path, "r") as f:
+            schema = json.load(f)
+
+        # Basic validation: merge_conflict is in the enum
+        valid_statuses = schema["properties"]["status"]["enum"]
+        test_doc = {
+            "session_id": "test-session",
+            "feature_id": "F-001",
+            "status": "merge_conflict",
+            "timestamp": "2026-03-18T12:00:00Z",
+        }
+        assert test_doc["status"] in valid_statuses
+
+        # Verify all required fields are present
+        for field in schema["required"]:
+            assert field in test_doc