borisxdave 0.3.0__py3-none-any.whl → 0.3.2__py3-none-any.whl

boris_prompt_data.py

@@ -0,0 +1,194 @@
+"""Boris prompt embedded as a Python string for reliable pip installation."""
+
+BORIS_PROMPT = r"""# Boris - Project Manager Orchestrator
+
+Boris is a **project manager**, He plans, delegates, and verifies. DaveLoop is the builder.
+
+---
+
+## Boris's Job
+
+1. **Plan** - Break the user's task into ordered milestones
+2. **Craft** - Write precise, context-rich prompts for each milestone
+3. **Delegate** - Spawn DaveLoop with the crafted prompt
+4. **Verify** - Check DaveLoop's output against acceptance criteria
+5. **Manage Git** - init git add and stage then commit when user request fully built
+6. **Repeat** - Move to next milestone until project is done
+
+---
+
+## How Boris Writes Prompts for DaveLoop
+
+This is the most critical part. DaveLoop is a self-healing debug loop - it receives a bug/task description and iterates until resolved. Boris must give DaveLoop everything it needs in ONE prompt.
+
+### Every DaveLoop prompt MUST include:
+
+1. **What the project is** - High-level description so DaveLoop understands context
+2. **What already exists** - Exact files and modules from completed milestones
+3. **What to build NOW** - The specific milestone spec, detailed and unambiguous
+4. **How it integrates** - Which existing files to import from, which functions to call
+5. **Acceptance criteria** - Concrete, testable criteria DaveLoop can verify
+6. **Boundaries** - What NOT to touch (files from other milestones)
+7. **Verification steps** - Exact commands to prove the milestone works
+
+### Prompt quality rules:
+
+- **Be specific, not vague** - "Create a Flask app with /api/users GET endpoint returning JSON" not "build a backend"
+- **Name files explicitly** - "Create src/routes/users.py" not "create the routes"
+- **Name functions explicitly** - "Implement get_users() that queries the User model" not "add user functionality"
+- **Describe data flow** - "The frontend calls /api/users, which calls db.get_all_users(), which returns List[User]"
+- **Include test commands** - "Verify with: python -m pytest tests/test_users.py -v"
+
+---
+
+## How Boris Checks DaveLoop's Work
+
+After DaveLoop finishes, Boris checks:
+
+1. **Did DaveLoop report [DAVELOOP:RESOLVED]?** - If yes, likely success
+2. **Did DaveLoop's exit code = 0?** - If not, something crashed
+3. **Do the acceptance criteria pass?** - Boris can ask Claude to analyze the output
+4. **Did DaveLoop stay in scope?** - No scope creep into other milestones
+
+### Verdicts:
+- **RESOLVED** - Milestone done, commit and move on
+- **OFF_PLAN** - DaveLoop built the wrong thing, send correction prompt
+- **FAILED** - DaveLoop couldn't finish, retry or skip
+
+---
+
+## How Boris Monitors DaveLoop in Real-Time
+
+Boris doesn't just fire-and-forget. He watches DaveLoop's output line by line as it streams.
+
+### Reasoning Block = Boris Check-in
+
+DaveLoop outputs structured reasoning blocks (KNOWN/UNKNOWN/HYPOTHESIS/NEXT/WHY) before every action. Each reasoning block triggers a **Boris check-in** - Boris reports what DaveLoop accomplished since the last reasoning block and what he's about to do next:
+
+```
+  [Boris] === DaveLoop Check-in #3 ===
+  [Boris] Done so far:
+  [Boris]   - Created models.py
+  [Boris]   - Created config.py
+  [Boris]   - Ran tests: pytest tests/ -v
+  [Boris] Knows: Database models created, need seed data next
+  [Boris] Thinking: Seed data should include sample products and users
+  [Boris] Next: Create seed_data.py with 10 sample products
+  [Boris] ===========================
+```
+
+Boris tracks every file write, edit, bash command, and test result between reasoning blocks. When a new reasoning block fires, Boris summarizes what DaveLoop accomplished since the last check-in, plus DaveLoop's current thinking and next move.
+
+When DaveLoop finishes, Boris prints a full run summary of all tracked actions.
+
+### Off-Rail Detection and Text Interrupt
+
+Boris watches for signs that DaveLoop is going off-rail:
+- **Wrong files** - DaveLoop creating/modifying files outside the milestone's allowed list
+- **Scope creep** - DaveLoop mentioning "build the entire project" or "implement all milestones"
+- **Wrong milestone** - DaveLoop referencing other milestone IDs (M2, M3) while building M1
+
+When Boris detects off-rail behavior, he sends a **text interrupt** to DaveLoop's stdin:
+```
+  [Boris INTERRUPT] wait - you are creating orders.py which is outside the scope of M1.
+  Only touch: models.py, config.py. Focus on M1: Project Setup only.
+```
+
+DaveLoop supports text interrupts (wait/pause/add/done) and will process Boris's correction mid-run.
+
+### Interrupt Limits
+
+Boris sends a maximum of 3 interrupts per DaveLoop run. If DaveLoop keeps going off-rail after 3 interrupts, Boris lets it finish and handles it at the verdict stage (OFF_PLAN correction or FAILED retry).
+
+---
+
+## How Boris Handles Failures
+
+1. **First failure** - Retry with the same prompt (DaveLoop might just need another iteration)
+2. **Off-plan work** - Send correction prompt explaining what went wrong and what's expected
+3. **Repeated failure** - Skip milestone, log warning, continue with next milestone
+4. **Never get stuck** - Boris always moves forward. Skip and warn, don't loop forever.
+
+---
+
+## How Boris Manages Git
+
+After each RESOLVED milestone:
+1. `git add -A` in the project directory
+2. `git commit -m "feat(milestone-{id}): {title}"`
+3. `git push` if remote is configured
+
+On completion: final commit + push with "chore: Boris orchestration complete"
+
+---
+
+## Boris's State
+
+Boris saves progress after every milestone to `.boris/state.json` so he can resume if interrupted. The state tracks:
+- The full plan
+- Which milestones are completed/skipped/pending
+- Current milestone index
+- Retry counts
+- Timestamps
+
+---
+
+## How Boris Exits
+
+Boris always exits cleanly with a proper summary and exit code.
+
+### Exit Codes:
+- **0** - All milestones completed successfully
+- **1** - Some milestones were skipped or failed
+- **130** - Interrupted by user (Ctrl+C), state saved for resume
+
+### Summary Report:
+
+When Boris finishes (all milestones processed), he generates a **summary markdown file** at `plans/summary_YYYYMMDD_HHMMSS.md` containing:
+- The original task description
+- Total milestones: completed, skipped, failed
+- Per-milestone breakdown: status, title, files created/modified
+- Timestamps: start time, end time, total duration
+- Skipped milestones: reasons why they were skipped
+
+This summary is Boris's final deliverable - a complete record of what was built, what was skipped, and why.
+
+---
+
+## Phase 2: UI Testing & Polish (DaveLoop v1.4)
+
+After all structural milestones are completed, Boris enters the UI Testing & Polish phase.
+
+### How It Works:
+1. Boris asks Claude to create UI testing milestones (Claude already knows the project - it just built it)
+2. Claude decides the project type and test tool (Playwright for web, Maestro for mobile)
+3. Boris shifts DaveLoop to UI Tester Mode (v1.4) - same DaveLoop, different orders
+4. DaveLoop tests UI flows, finds issues, fixes them
+5. Boris verifies each UI milestone with UI-specific verdicts
+
+### DaveLoop v1.4 - UI Tester Mode:
+- Does NOT build new features
+- Tests existing UI flows with Playwright/Maestro
+- Reports issues: `ISSUE FOUND: <description>`
+- Applies fixes: `FIX APPLIED: <description>`
+- Captures screenshots for visual verification
+
+Boris doesn't teach DaveLoop how to use Playwright or Maestro. Boris scopes the task, ships DaveLoop off, and DaveLoop handles the rest.
+
+### Skip UI Testing:
+Use `--skip-ui` flag to skip the UI testing phase entirely.
+
+### Resume Support:
+If interrupted during UI testing, `boris -r -d <project>` resumes directly into the UI phase.
+
+---
+
+## Boris's Personality
+
+Boris is methodical, relentless, and focused:
+- He does not write code. He manages.
+- He does not discuss. He acts.
+- He does not get stuck. He moves forward.
+- He trusts DaveLoop to build. He verifies the results.
+- He keeps perfect records (state, logs, plan markdown, summary report).
+"""

{borisxdave-0.3.0.dist-info → borisxdave-0.3.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: borisxdave
-Version: 0.3.0
+Version: 0.3.2
 Summary: Boris - Autonomous Project Orchestrator
 Requires-Python: >=3.8
 

borisxdave-0.3.2.dist-info/RECORD

@@ -0,0 +1,14 @@
+boris.py,sha256=W5k3eNJzhHSKIAtzvwmTYHX7PBCaxxLwRzdAize6Xy8,63235
+boris_prompt_data.py,sha256=ZBvWMrQOBrl07cNFzgeGumJ54cYg0Be9RSSnK6a3YQY,7940
+config.py,sha256=KfFKyCGasdm1yBvIRFv-ykzA_oRo-zu1Euu9YC7V1Cg,324
+engine.py,sha256=Pdu0i4XrNxiU246EV8MjXvYp9CBvuJWGLA18QMIYvFM,37468
+file_lock.py,sha256=1YriAAayVy8YFe7JFuGIloiJWWvN2FSY0Ry1sB043Sc,4823
+git_manager.py,sha256=BuuTT4naPb5-jLhOik1xHM2ztzuKvJ_bnecZmlYgwFs,8493
+planner.py,sha256=UrU--kBvzvyD1gOVxIn-kdbJiu8tt4rcowsln66WkGw,5670
+prompts.py,sha256=-eSwZ-oTBR12Wx4Md57sVF816T9vHEFlMsvT4zMkwOg,35187
+state.py,sha256=2DCPlcM7SBlCkwWvcnIabltcduv74W46FZ7DxKurWkw,5752
+borisxdave-0.3.2.dist-info/METADATA,sha256=NxpmhoGuCnJCHbNc7bkV03dllb6AAGu-JacgT_JJIjk,133
+borisxdave-0.3.2.dist-info/WHEEL,sha256=hPN0AlP2dZM_3ZJZWP4WooepkmU9wzjGgCLCeFjkHLA,92
+borisxdave-0.3.2.dist-info/entry_points.txt,sha256=a6FLWgxiQjGMJIRSV5sDxaaaaQchunm04ZuzX8N7-6I,61
+borisxdave-0.3.2.dist-info/top_level.txt,sha256=C3fTm1vt0QEQyJtvSZiFiOvmR4d0hWmmr6hujJqFrQE,82
+borisxdave-0.3.2.dist-info/RECORD,,

{borisxdave-0.3.0.dist-info → borisxdave-0.3.2.dist-info}/top_level.txt

@@ -1,6 +1,8 @@
 boris
+boris_prompt_data
 config
 engine
+file_lock
 git_manager
 planner
 prompts

engine.py

@@ -1,6 +1,7 @@
 """Boris engine - execution and monitoring (merged from executor + monitor)."""
 import concurrent.futures
 import enum
+import json
 import logging
 import os
 import re
@@ -8,8 +9,10 @@ import shutil
 import subprocess
 import sys
 import tempfile
+import time
 from dataclasses import dataclass
 from datetime import datetime
+from pathlib import Path
 from typing import Optional
 
 # Force unbuffered stdout for real-time output on Windows
@@ -62,6 +65,49 @@ def _clean_output(text: str) -> str:
     return text
 
 
+# --- Worker Status (B7: Swarm Dashboard) ---
+
+
+def _write_worker_status(project_dir: str, milestone_id: str, status: dict):
+    """Write worker status to .boris/workers/ for the swarm dashboard."""
+    try:
+        status_dir = Path(project_dir) / ".boris" / "workers"
+        status_dir.mkdir(parents=True, exist_ok=True)
+        status_file = status_dir / f"{milestone_id}.json"
+        status["updated_at"] = time.time()
+        status_file.write_text(json.dumps(status, indent=2), encoding="utf-8")
+    except OSError:
+        pass  # Non-critical: dashboard is informational only
+
+
+def read_worker_statuses(project_dir: str) -> dict:
+    """Read all worker status files from .boris/workers/. Returns {milestone_id: status_dict}."""
+    statuses = {}
+    status_dir = Path(project_dir) / ".boris" / "workers"
+    if not status_dir.exists():
+        return statuses
+    for status_file in status_dir.glob("*.json"):
+        try:
+            data = json.loads(status_file.read_text(encoding="utf-8"))
+            milestone_id = status_file.stem
+            statuses[milestone_id] = data
+        except (json.JSONDecodeError, OSError):
+            pass
+    return statuses
+
+
+def clear_worker_statuses(project_dir: str):
+    """Remove all worker status files (call after a batch completes)."""
+    status_dir = Path(project_dir) / ".boris" / "workers"
+    if not status_dir.exists():
+        return
+    for status_file in status_dir.glob("*.json"):
+        try:
+            status_file.unlink()
+        except (FileNotFoundError, OSError):
+            pass
+
+
 # --- Execution (from executor.py) ---
 
 
@@ -246,6 +292,17 @@ def run(prompt: str, project_dir: str, max_iterations: int = None,
 
         print(f"  [Boris] Spawning DaveLoop: max_iter={max_iter}, project={project_dir}", flush=True)
         logger.info("Spawning DaveLoop: max_iter=%d, project=%s", max_iter, project_dir)
+
+        # Write initial worker status for dashboard (B7)
+        if milestone:
+            _write_worker_status(project_dir, milestone.id, {
+                "milestone_id": milestone.id,
+                "title": milestone.title,
+                "state": "starting",
+                "started_at": time.time(),
+                "actions": 0,
+                "interrupts": 0,
+            })
         logger.debug("Prompt length: %d chars", len(prompt))
 
         # Boris's own log for this execution
@@ -280,6 +337,14 @@ def run(prompt: str, project_dir: str, max_iterations: int = None,
         all_accomplishments = []   # cumulative for the whole run
         interrupt_count = 0
         MAX_INTERRUPTS = 3  # After 3 interrupts, let DaveLoop finish and fail at verdict
+        # Off-rail detection is suppressed during prompt echo phase.
+        # DaveLoop echoes/processes the prompt at startup, which contains sibling
+        # milestone IDs (from the PARALLEL EXECUTION WARNING section). Without this
+        # guard, _check_off_rail() fires false positives on the prompt's own text.
+        # We suppress until DaveLoop starts actual work (first reasoning block) or
+        # after a generous line threshold.
+        offrail_active = False
+        OFFRAIL_WARMUP_LINES = 80  # Lines before off-rail activates even without reasoning
 
         for raw_line in process.stdout:
             line = raw_line.decode("utf-8", errors="replace")
@@ -298,10 +363,17 @@ def run(prompt: str, project_dir: str, max_iterations: int = None,
                     accomplishments.append(acc)
                     all_accomplishments.append(acc)
 
+            # Activate off-rail detection after warmup threshold (prompt echo complete)
+            if not offrail_active and len(output_lines) >= OFFRAIL_WARMUP_LINES:
+                offrail_active = True
+
             # --- Reasoning block detection ---
             if "REASONING" in clean and ("===" in clean or "---" in clean or "KNOWN" in clean):
                 in_reasoning = True
                 reasoning_lines = []
+                # First reasoning block means DaveLoop is doing real work - activate off-rail
+                if not offrail_active:
+                    offrail_active = True
                 continue
 
             if in_reasoning:
@@ -317,14 +389,26 @@ def run(prompt: str, project_dir: str, max_iterations: int = None,
                                 reasoning[key] = rl.split(":", 1)[1].strip()
                     if reasoning:
                         _boris_commentary(reasoning, reasoning_count, accomplishments)
+                    # Update worker status for dashboard (B7)
+                    if milestone:
+                        _write_worker_status(project_dir, milestone.id, {
+                            "milestone_id": milestone.id,
+                            "title": milestone.title,
+                            "state": "working",
+                            "started_at": time.time(),
+                            "reasoning_blocks": reasoning_count,
+                            "actions": len(all_accomplishments),
+                            "interrupts": interrupt_count,
+                            "last_action": all_accomplishments[-1] if all_accomplishments else None,
+                        })
                     # Reset per-block accomplishments, keep cumulative
                     accomplishments = []
                     reasoning_lines = []
                 else:
                     reasoning_lines.append(clean)
 
-            # --- Off-rail detection ---
-            if milestone and interrupt_count < MAX_INTERRUPTS:
+            # --- Off-rail detection (suppressed during prompt echo phase) ---
+            if milestone and interrupt_count < MAX_INTERRUPTS and offrail_active:
                 interrupt_msg = _check_off_rail(clean, milestone)
                 if interrupt_msg:
                     _send_interrupt(process, interrupt_msg, boris_log)
@@ -332,12 +416,29 @@ def run(prompt: str, project_dir: str, max_iterations: int = None,
                     if interrupt_count >= MAX_INTERRUPTS:
                         warn = (
                             f"[Boris] Sent {MAX_INTERRUPTS} interrupts. "
-                            f"DaveLoop keeps going off-rail. Will check at verdict."
+                            f"DaveLoop keeps going off-rail. Terminating process."
                         )
                         print(f"\n  {warn}\n", flush=True)
-                        logger.warning(warn)
+                        logger.warning("Terminating DaveLoop process after %d ignored interrupts", MAX_INTERRUPTS)
                         if boris_log:
                             boris_log.write(f"\n{warn}\n")
+                        # Hard kill: terminate the process since interrupts are being ignored
+                        process.terminate()
+                        try:
+                            process.wait(timeout=10)
+                        except subprocess.TimeoutExpired:
+                            process.kill()
+                            process.wait(timeout=5)
+                        output = "".join(output_lines)
+                        boris_log.write(f"\n=== DaveLoop FORCE KILLED after {MAX_INTERRUPTS} ignored interrupts ===\n")
+                        boris_log.close()
+                        boris_log = None  # prevent double-close in finally
+                        return ExecutionResult(
+                            output=output,
+                            exit_code=-1,
+                            resolved=False,
+                            log_path=log_path,
+                        )
 
         process.wait()
         output = "".join(output_lines)
@@ -414,28 +515,125 @@ def _setup_log(project_dir: str) -> str:
     return os.path.join(_LOGS_DIR, f"boris_exec_{timestamp}.log")
 
 
-def run_parallel(tasks: list, project_dir: str, max_iterations: int = None) -> list:
+def _create_worktree(project_dir: str, milestone_id: str) -> tuple:
+    """Create a git worktree for a milestone. Returns (worktree_path, branch_name) or None on failure."""
+    worktree_path = os.path.join(project_dir, f".boris_worktree_{milestone_id}")
+    branch_name = f"boris/{milestone_id}"
+    try:
+        result = subprocess.run(
+            ["git", "worktree", "add", "-b", branch_name, worktree_path],
+            cwd=project_dir, capture_output=True, timeout=30,
+            encoding="utf-8", errors="replace",
+        )
+        if result.returncode == 0:
+            logger.info("Created worktree for %s at %s", milestone_id, worktree_path)
+            return (worktree_path, branch_name)
+        else:
+            logger.warning("Failed to create worktree for %s: %s", milestone_id, result.stderr.strip())
+            return None
+    except (subprocess.SubprocessError, OSError) as e:
+        logger.warning("Worktree creation error for %s: %s", milestone_id, e)
+        return None
+
+
+def _merge_worktree(project_dir: str, worktree_path: str, branch_name: str, milestone_id: str) -> bool:
+    """Merge a worktree branch back into the current branch and clean up. Returns success."""
+    try:
+        # Merge the branch back
+        merge_result = subprocess.run(
+            ["git", "merge", branch_name, "--no-edit", "-m",
+             f"Merge boris/{milestone_id} worktree back"],
+            cwd=project_dir, capture_output=True, timeout=60,
+            encoding="utf-8", errors="replace",
+        )
+        if merge_result.returncode != 0:
+            logger.warning("Merge failed for %s: %s", milestone_id, merge_result.stderr.strip())
+            # Abort merge on conflict
+            subprocess.run(["git", "merge", "--abort"], cwd=project_dir,
+                          capture_output=True, timeout=10)
+            return False
+        return True
+    except (subprocess.SubprocessError, OSError) as e:
+        logger.warning("Merge error for %s: %s", milestone_id, e)
+        return False
+    finally:
+        _cleanup_worktree(project_dir, worktree_path, branch_name)
+
+
+def _cleanup_worktree(project_dir: str, worktree_path: str, branch_name: str):
+    """Remove a git worktree and its branch."""
+    try:
+        subprocess.run(["git", "worktree", "remove", worktree_path, "--force"],
+                      cwd=project_dir, capture_output=True, timeout=30)
+    except (subprocess.SubprocessError, OSError):
+        pass
+    try:
+        subprocess.run(["git", "branch", "-D", branch_name],
+                      cwd=project_dir, capture_output=True, timeout=10)
+    except (subprocess.SubprocessError, OSError):
+        pass
+
+
+def run_parallel(tasks: list, project_dir: str, max_iterations: int = None,
+                 isolation: str = "none") -> list:
     """Run multiple DaveLoop instances in parallel using ThreadPoolExecutor.
 
     Args:
         tasks: List of (prompt, milestone) tuples.
         project_dir: Working directory for the project.
         max_iterations: Max DaveLoop iterations per milestone.
+        isolation: Isolation strategy - "none" (shared dir), "worktree" (git worktrees).
 
     Returns:
         List of (milestone, ExecutionResult) tuples, one per input task.
     """
     results = []
 
-    def _run_one(prompt_milestone):
-        prompt, milestone = prompt_milestone
-        result = run(prompt, project_dir, max_iterations, milestone=milestone)
-        return (milestone, result)
-
-    with concurrent.futures.ThreadPoolExecutor(max_workers=len(tasks)) as executor:
-        futures = {executor.submit(_run_one, t): t for t in tasks}
-        for future in concurrent.futures.as_completed(futures):
-            results.append(future.result())
+    if isolation == "worktree" and len(tasks) > 1:
+        # Create worktrees for each task
+        worktree_map = {}  # milestone_id -> (worktree_path, branch_name)
+        for prompt, milestone in tasks:
+            wt = _create_worktree(project_dir, milestone.id)
+            if wt:
+                worktree_map[milestone.id] = wt
+            else:
+                logger.warning("Worktree failed for %s, falling back to shared dir", milestone.id)
+
+        def _run_one_worktree(prompt_milestone):
+            prompt, milestone = prompt_milestone
+            wt_info = worktree_map.get(milestone.id)
+            work_dir = wt_info[0] if wt_info else project_dir
+            result = run(prompt, work_dir, max_iterations, milestone=milestone)
+            return (milestone, result)
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=len(tasks)) as executor:
+            futures = {executor.submit(_run_one_worktree, t): t for t in tasks}
+            for future in concurrent.futures.as_completed(futures):
+                milestone, result = future.result()
+                # Merge worktree back if it was used
+                wt_info = worktree_map.get(milestone.id)
+                if wt_info and result.resolved:
+                    wt_path, branch = wt_info
+                    merge_ok = _merge_worktree(project_dir, wt_path, branch, milestone.id)
+                    if not merge_ok:
+                        print(f"  [Boris] WARNING: Merge conflict for {milestone.id} worktree", flush=True)
+                        logger.warning("Worktree merge conflict for %s", milestone.id)
+                elif wt_info:
+                    # Failed milestone - just clean up worktree
+                    _cleanup_worktree(project_dir, wt_info[0], wt_info[1])
+                results.append((milestone, result))
+
+    else:
+        # No isolation or single task - original behavior
+        def _run_one(prompt_milestone):
+            prompt, milestone = prompt_milestone
+            result = run(prompt, project_dir, max_iterations, milestone=milestone)
+            return (milestone, result)
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=len(tasks)) as executor:
+            futures = {executor.submit(_run_one, t): t for t in tasks}
+            for future in concurrent.futures.as_completed(futures):
+                results.append(future.result())
 
     return results
 

file_lock.py

@@ -0,0 +1,123 @@
+"""File-level locking for parallel swarm workers.
+
+Prevents parallel DaveLoop agents from corrupting shared files by providing
+file-level locks via atomic file creation. Works on both Windows and Unix.
+"""
+import json
+import os
+import time
+from contextlib import contextmanager
+from pathlib import Path
+
+
+class FileLockManager:
+    """Manages file-level locks for parallel swarm workers.
+
+    Lock state is stored in .boris/locks/ in the project directory.
+    Each lock is an atomic file recording: owner (milestone ID), timestamp, file path.
+    """
+
+    def __init__(self, project_dir: str):
+        self.lock_dir = Path(project_dir) / ".boris" / "locks"
+        self.lock_dir.mkdir(parents=True, exist_ok=True)
+
+    def _lock_path(self, filepath: str) -> Path:
+        """Get the lock file path for a given source file."""
+        normalized = os.path.normpath(filepath)
+        # Replace path separators with underscores for flat lock directory
+        safe_name = normalized.replace(os.sep, "_").replace("/", "_").replace("\\", "_")
+        return self.lock_dir / f"{safe_name}.lock"
+
+    @contextmanager
+    def lock_file(self, filepath: str, owner: str, timeout: int = 30):
+        """Acquire a lock on a file. Blocks until available or timeout.
+
+        Args:
+            filepath: The file to lock (relative or absolute path).
+            owner: Identifier for the lock owner (e.g. milestone ID).
+            timeout: Max seconds to wait for the lock.
+
+        Raises:
+            TimeoutError: If the lock cannot be acquired within timeout.
+        """
+        lock_path = self._lock_path(filepath)
+        start = time.time()
+
+        while True:
+            try:
+                # Atomic create-or-fail: 'x' mode fails if file exists
+                fd = open(lock_path, "x", encoding="utf-8")
+                fd.write(json.dumps({
+                    "owner": owner,
+                    "file": filepath,
+                    "time": time.time(),
+                }))
+                fd.close()
+                break
+            except FileExistsError:
+                if time.time() - start > timeout:
+                    # Read who holds the lock for better error messages
+                    try:
+                        holder = json.loads(lock_path.read_text(encoding="utf-8"))
+                        holder_info = f" (held by {holder.get('owner', 'unknown')})"
+                    except Exception:
+                        holder_info = ""
+                    raise TimeoutError(
+                        f"Could not acquire lock on {filepath}{holder_info} "
+                        f"after {timeout}s"
+                    )
+                time.sleep(0.5)
+
+        try:
+            yield
+        finally:
+            try:
+                lock_path.unlink()
+            except FileNotFoundError:
+                pass
+
+    def get_locked_files(self) -> dict:
+        """Return dict of currently locked files and their owners."""
+        locks = {}
+        for lock_file in self.lock_dir.glob("*.lock"):
+            try:
+                data = json.loads(lock_file.read_text(encoding="utf-8"))
+                original_file = data.get("file", lock_file.stem.replace("_", os.sep))
+                locks[original_file] = data.get("owner", "unknown")
+            except (json.JSONDecodeError, KeyError, OSError):
+                pass
+        return locks
+
+    def is_locked(self, filepath: str) -> bool:
+        """Check if a file is currently locked."""
+        lock_path = self._lock_path(filepath)
+        return lock_path.exists()
+
+    def lock_owner(self, filepath: str) -> str:
+        """Return the owner of the lock on a file, or None if unlocked."""
+        lock_path = self._lock_path(filepath)
+        if not lock_path.exists():
+            return None
+        try:
+            data = json.loads(lock_path.read_text(encoding="utf-8"))
+            return data.get("owner")
+        except (json.JSONDecodeError, KeyError, OSError):
+            return None
+
+    def release_all(self, owner: str):
+        """Release all locks held by a specific owner (milestone cleanup)."""
+        for lock_file in self.lock_dir.glob("*.lock"):
+            try:
+                data = json.loads(lock_file.read_text(encoding="utf-8"))
+                if data.get("owner") == owner:
+                    lock_file.unlink()
+            except (json.JSONDecodeError, KeyError, FileNotFoundError, OSError):
+                pass
+
+    def cleanup(self):
+        """Remove all lock files (use after all workers complete)."""
+        for lock_file in self.lock_dir.glob("*.lock"):
+            try:
+                lock_file.unlink()
+            except (FileNotFoundError, OSError):
+                pass