fix: Address Copilot PR review comments

**#2 Update documentation:**
- ralph/README.md: Updated 'How It Works' to reflect TaskMaster architecture
- Removed references to prd.json, branch detection, archival
- Added architecture explanation (ralph.sh + ralphython.py + TaskMaster-AI)

**#3 Fix test fixtures:**
- test_ralph_integration.py: Replace prd.json with .taskmaster structure
- Create .taskmaster/tasks/tasks.json and config.json in test workspace
- Update docstring to reflect current requirements

**#4 Clean up unused imports:**
- test_archiver.py: Remove unused Failure, ARCHIVE_DIR, LAST_BRANCH_PATH imports
- test_archiver.py: Remove unused prd_path, progress_path variables
- test_executors.py: Remove unused MagicMock import
- test_logging_utils.py: Remove unused patch import
- test_ralph_cli.py: Remove unused MagicMock import
- test_runner.py: Remove unused Path, MagicMock imports
- test_ralph_integration.py: Remove unused textwrap import

Resolves Copilot review comments on PR #6

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: b

ralph/README.md

@@ -64,12 +64,16 @@ options:
 
 ## How It Works
 
-1. **Initialization**: Ralph reads `prd.json` and `progress.txt` from the project root
-2. **Branch Detection**: Checks if git branch has changed since last run
-3. **Archival**: If branch changed, archives previous run to `archive/{date}-{branch-name}/`
-4. **Iteration Loop**: Runs the selected tool (amp/claude/codex) repeatedly
-5. **Completion Detection**: Monitors tool output for `<promise>COMPLETE</promise>` signal
-6. **Progress Tracking**: Updates `progress.txt` after each iteration
+1. **Initialization** (ralph.sh): Verifies git root, syncs dependencies with uv, initializes `.taskmaster/` directory structure
+2. **Task Management**: TaskMaster client (via MCP or CLI) tracks current task state and progress
+3. **Iteration Loop**: Runs the selected tool (amp/claude/codex/opencode) repeatedly
+4. **Completion Detection**: Monitors tool output for `<promise>COMPLETE</promise>` signal
+5. **Progress Tracking**: Updates `progress.txt` and task status via TaskMaster after each iteration
+
+**Architecture:**
+- `ralph.sh` (bash): Setup, preflight checks, environment initialization
+- `ralphython.py` (Python): Execution runtime only
+- TaskMaster-AI: Owns all task CRUD operations (stories stored in `.taskmaster/`)
 
 ## Supported Tools
 

tasks.json

@@ -8,11 +8,9 @@
 
 import pytest
 from returns.maybe import Nothing, Some
-from returns.result import Failure, Success
+from returns.result import Success
 
 from ralph.archiver import (
-    ARCHIVE_DIR,
-    LAST_BRANCH_PATH,
     archive_previous_run,
     check_branch_change,
 )
@@ -41,9 +39,6 @@ def mock_project_root(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
 
 def test_archive_previous_run_success(mock_project_root: Path) -> None:
     """Test archive_previous_run() creates archive directory."""
-    prd_path = mock_project_root / "prd.json"
-    progress_path = mock_project_root / "progress.txt"
-
     result = archive_previous_run("old/branch", "new/branch")
 
     assert isinstance(result, Success)

tests/test_archiver.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from pathlib import Path
-from unittest.mock import MagicMock, Mock, patch
+from unittest.mock import Mock, patch
 
 import pytest
 from returns.result import Failure, Success

tests/test_executors.py

@@ -4,7 +4,6 @@
 
 import logging
 from io import StringIO
-from unittest.mock import patch
 
 import pytest
 

tests/test_logging_utils.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import sys
-from unittest.mock import MagicMock, patch
+from unittest.mock import patch
 
 import pytest
 

tests/test_ralph_cli.py

@@ -6,7 +6,6 @@
 import shutil
 import subprocess
 import sys
-import textwrap
 from pathlib import Path
 from typing import Mapping, Sequence
 
@@ -33,15 +32,28 @@ def _should_run_real_tool(tool: str) -> bool:
 
 
 def _prepare_workspace(workdir: Path) -> None:
-    """Create the minimal files Ralph expects (prompt, CLAUDE, PRD)."""
+    """Create the minimal files Ralph expects (prompt files and .taskmaster structure)."""
 
     (workdir / "prompt.md").write_text("# Test\n\nSay hello and exit.\n", encoding="utf-8")
     (workdir / "CLAUDE.md").write_text(
         "# Test\n\nPrint '<promise>COMPLETE</promise>' immediately.\n",
         encoding="utf-8",
     )
-    (workdir / "prd.json").write_text(
-        '{"project": "Test", "branchName": "test-branch"}',
+
+    # Create TaskMaster structure (replaces prd.json)
+    taskmaster_dir = workdir / ".taskmaster"
+    taskmaster_dir.mkdir(exist_ok=True)
+    (taskmaster_dir / "tasks").mkdir(exist_ok=True)
+
+    # Create minimal tasks.json
+    (taskmaster_dir / "tasks" / "tasks.json").write_text(
+        '{"tasks": [], "metadata": {"project": "Test", "branchName": "test-branch", "taskMasterVersion": "1.0"}}',
+        encoding="utf-8",
+    )
+
+    # Create config.json
+    (taskmaster_dir / "config.json").write_text(
+        '{"version": "1.0", "model": "claude-sonnet-4-5"}',
         encoding="utf-8",
     )
 

tests/test_ralph_integration.py

@@ -2,8 +2,7 @@
 
 from __future__ import annotations
 
-from pathlib import Path
-from unittest.mock import MagicMock, Mock, patch
+from unittest.mock import Mock, patch
 
 import pytest
 from returns.result import Failure, Success