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

Users/david/AppData/Local/Programs/Python/Python313/Lib/site-packages/boris_prompt.md

@@ -0,0 +1,191 @@
+# 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).

boris.py

@@ -28,6 +28,123 @@ DEFAULT_MAX_ITERATIONS = 15
 MAX_CORRECTIONS = 2
 MAX_RETRIES = 1
 
+# Swarm mode configuration presets
+SWARM_PRESETS = {
+    "conservative": {
+        "swarm_budget": 3,
+        "swarm_depth": 1,
+        "isolation": "worktree",
+        "no_converge": False,
+    },
+    "balanced": {
+        "swarm_budget": 5,
+        "swarm_depth": 1,
+        "isolation": "worktree",
+        "no_converge": False,
+    },
+    "aggressive": {
+        "swarm_budget": 10,
+        "swarm_depth": 2,
+        "isolation": "worktree",
+        "no_converge": False,
+    },
+    "yolo": {  # Closest to the original emergent behavior
+        "swarm_budget": 999,
+        "swarm_depth": 2,
+        "isolation": "none",
+        "no_converge": True,
+    },
+}
+
+
+class TokenEstimator:
+    """Estimates token usage for Boris orchestration.
+
+    Claude Code runs on a token-based subscription model, not pay-per-API-call.
+    This estimator helps users understand token consumption before committing to
+    a task, and allows setting token budgets to limit usage.
+
+    Token estimates are based on realistic DaveLoop iteration profiles:
+    - Base iteration: ~4000 input tokens (prompt) + ~2000 output tokens (response)
+    - Context growth: each iteration adds ~1500 tokens of accumulated context
+    - Sub-agent spawn: ~3000 tokens each
+    - Convergence run: ~5000 tokens (reads multiple files + analysis)
+    """
+
+    BASE_INPUT_TOKENS = 4000       # Base input tokens per DaveLoop iteration
+    BASE_OUTPUT_TOKENS = 2000      # Base output tokens per DaveLoop iteration
+    CONTEXT_GROWTH_PER_ITER = 1500 # Additional context tokens accumulated per iteration
+    TOKENS_PER_SUB_AGENT = 3000   # Tokens per sub-agent spawn
+    TOKENS_PER_CONVERGENCE = 5000 # Tokens per convergence run
+
+    def __init__(self, max_tokens: int = None):
+        self.max_tokens = max_tokens
+        self.estimated_tokens = 0
+
+    def _tokens_per_iteration(self, iteration_num: int) -> int:
+        """Estimate tokens for a single DaveLoop iteration, accounting for context growth."""
+        input_tokens = self.BASE_INPUT_TOKENS + (iteration_num * self.CONTEXT_GROWTH_PER_ITER)
+        return input_tokens + self.BASE_OUTPUT_TOKENS
+
+    def record_tokens(self, amount: int):
+        """Record estimated token usage."""
+        self.estimated_tokens += amount
+
+    def estimate_batch(self, num_workers: int, avg_iterations: int,
+                       avg_sub_agents: int) -> int:
+        """Estimate tokens for a batch of parallel workers."""
+        worker_tokens = 0
+        for w in range(num_workers):
+            for i in range(avg_iterations):
+                worker_tokens += self._tokens_per_iteration(i)
+        sub_agent_tokens = num_workers * avg_sub_agents * self.TOKENS_PER_SUB_AGENT
+        convergence_tokens = self.TOKENS_PER_CONVERGENCE
+        return worker_tokens + sub_agent_tokens + convergence_tokens
+
+    def estimate_task(self, plan) -> dict:
+        """Estimate total tokens for a Boris plan.
+
+        Returns a dict with breakdown: per-milestone estimates, sub-agent tokens,
+        convergence tokens, and total.
+        """
+        milestones = plan.milestones
+        num_milestones = len(milestones)
+        avg_iterations = 8  # Typical DaveLoop iterations per milestone
+
+        milestone_tokens = 0
+        for i in range(avg_iterations):
+            milestone_tokens += self._tokens_per_iteration(i)
+        total_milestone_tokens = milestone_tokens * num_milestones
+
+        # Estimate convergence runs (one per parallel batch, assume ~ceil(milestones/3) batches)
+        estimated_batches = max(1, (num_milestones + 2) // 3)
+        convergence_tokens = estimated_batches * self.TOKENS_PER_CONVERGENCE
+
+        total = total_milestone_tokens + convergence_tokens
+
+        return {
+            "num_milestones": num_milestones,
+            "avg_iterations_per_milestone": avg_iterations,
+            "tokens_per_milestone": milestone_tokens,
+            "total_milestone_tokens": total_milestone_tokens,
+            "convergence_tokens": convergence_tokens,
+            "total_tokens": total,
+        }
+
+    def check_budget(self, estimated_additional: int) -> bool:
+        """Check if estimated additional tokens fit within budget."""
+        if self.max_tokens is None:
+            return True
+        return (self.estimated_tokens + estimated_additional) <= self.max_tokens
+
+    def summary(self) -> dict:
+        """Return token tracking summary."""
+        return {
+            "estimated_tokens": self.estimated_tokens,
+            "max_tokens": self.max_tokens,
+            "remaining": (self.max_tokens - self.estimated_tokens) if self.max_tokens else None,
+        }
+
 
 def setup_logging() -> logging.Logger:
     """Set up logging to both console and file."""
@@ -82,6 +199,61 @@ def print_plan_summary(plan: state_module.Plan):
     print(flush=True)
 
 
+def prompt_skip_milestones(plan: state_module.Plan, logger: logging.Logger) -> set:
+    """Prompt the user to optionally skip milestones before execution.
+
+    Returns a set of milestone IDs that were marked as skipped.
+    """
+    valid_ids = {m.id for m in plan.milestones}
+
+    try:
+        user_input = input("Enter milestone IDs to skip (comma-separated), or press Enter to run all: ").strip()
+    except EOFError:
+        # Non-interactive environment, skip nothing
+        return set()
+
+    if not user_input:
+        return set()
+
+    # Parse comma-separated milestone IDs
+    requested_ids = {s.strip().upper() for s in user_input.split(",") if s.strip()}
+    skip_ids = requested_ids & valid_ids
+    invalid_ids = requested_ids - valid_ids
+
+    if invalid_ids:
+        print(f"[Boris] WARNING: Unknown milestone IDs ignored: {', '.join(sorted(invalid_ids))}", flush=True)
+        logger.warning("Unknown milestone IDs in skip request: %s", invalid_ids)
+
+    if not skip_ids:
+        return set()
+
+    # Check for dependency warnings: if a skipped milestone is depended on by a non-skipped one
+    skipped_set = skip_ids
+    for m in plan.milestones:
+        if m.id in skipped_set:
+            continue
+        depends_on_skipped = [dep for dep in m.depends_on if dep in skipped_set]
+        if depends_on_skipped:
+            print(
+                f"[Boris] WARNING: {m.id} ({m.title}) depends on skipped milestone(s): "
+                f"{', '.join(depends_on_skipped)}",
+                flush=True,
+            )
+            logger.warning(
+                "Milestone %s depends on skipped milestone(s): %s",
+                m.id, depends_on_skipped,
+            )
+
+    # Mark milestones as skipped
+    for m in plan.milestones:
+        if m.id in skip_ids:
+            m.status = "skipped"
+            print(f"[Boris] Skipping milestone {m.id}: {m.title}", flush=True)
+            logger.info("User skipped milestone %s: %s", m.id, m.title)
+
+    return skip_ids
+
+
 def generate_summary(plan: state_module.Plan, project_dir: str, start_time: datetime) -> str:
     """Generate a summary markdown file and return its path."""
     os.makedirs(PLANS_DIR, exist_ok=True)
@@ -245,6 +417,41 @@ def parse_args() -> argparse.Namespace:
         help="Stop execution after completing this milestone ID (e.g. M4). Implies --incremental."
     )
 
+    # Swarm mode flags
+    parser.add_argument(
+        "--swarm", action="store_true",
+        help="Enable swarm mode: DaveLoops can spawn sub-agents via Task tool"
+    )
+    parser.add_argument(
+        "--swarm-budget", type=int, default=5,
+        help="Max sub-agents per DaveLoop worker in swarm mode (default: 5)"
+    )
+    parser.add_argument(
+        "--swarm-depth", type=int, default=1, choices=[1, 2],
+        help="Max sub-agent depth in swarm mode (default: 1, no recursive spawning)"
+    )
+    parser.add_argument(
+        "--preset", choices=["conservative", "balanced", "aggressive", "yolo"],
+        help="Apply a swarm configuration preset (implies --swarm)"
+    )
+    parser.add_argument(
+        "--isolation", choices=["none", "worktree"], default="none",
+        help="Isolation strategy for parallel workers (default: none)"
+    )
+    parser.add_argument(
+        "--no-converge", action="store_true", dest="no_converge",
+        help="Skip convergence phase after each swarm batch"
+    )
+    parser.add_argument(
+        "--max-tokens", type=int, default=None, dest="max_tokens",
+        help="Maximum estimated token budget for swarm/turbo mode execution (e.g. 500000)"
+    )
+    parser.add_argument(
+        "--estimate", metavar="TASK", nargs="?", const="__FROM_TASK__", dest="estimate",
+        help="Generate plan and print token estimate WITHOUT executing. "
+             "Use alone (boris --estimate 'task') or with positional task."
+    )
+
     return parser.parse_args()
 
 
@@ -516,16 +723,177 @@ def _process_milestone_verdict(verdict_result, result, milestone, plan, st, proj
             state_module.save(st)
 
 
+def validate_turbo_batch(ready: list, plan: state_module.Plan, logger: logging.Logger) -> list:
+    """Filter out milestones from a turbo batch whose dependencies were skipped.
+
+    These milestones cannot succeed without their dependency's output.
+    Also enforces foundation-first: first batch only runs milestones with no dependencies.
+    """
+    skipped_ids = {m.id for m in plan.milestones if m.status == "skipped"}
+    valid = []
+    for m in ready:
+        skipped_deps = [d for d in m.depends_on if d in skipped_ids]
+        if skipped_deps:
+            logger.warning(
+                "Milestone %s depends on skipped milestone(s) %s - deferring from turbo batch",
+                m.id, skipped_deps
+            )
+            print(f"[Boris] WARNING: {m.id} skipped from turbo batch - depends on skipped: {skipped_deps}", flush=True)
+        else:
+            valid.append(m)
+    return valid
+
+
+def _run_convergence(st, plan, project_dir, batch_milestones, logger):
+    """Run a convergence agent after a parallel batch to resolve conflicts."""
+    completed_in_batch = [m for m in batch_milestones if m.status == "completed"]
+    if len(completed_in_batch) < 2:
+        return  # No conflicts possible with 0-1 completed milestones
+
+    # Collect all files touched by this batch and check for overlaps
+    file_owners = {}
+    conflicts = []
+    for m in completed_in_batch:
+        for f in (m.files_to_create or []) + (m.files_to_modify or []):
+            if f in file_owners:
+                conflicts.append((f, file_owners[f], m.id))
+            file_owners[f] = m.id
+
+    if not conflicts:
+        logger.info("Convergence: No file conflicts detected in batch")
+        print("[Boris] Convergence: No conflicts detected. Skipping.", flush=True)
+        return
+
+    print(f"[Boris] Convergence: {len(conflicts)} potential conflict(s) detected", flush=True)
+    for filepath, owner1, owner2 in conflicts:
+        print(f"  [Boris]   {filepath}: written by {owner1} and {owner2}", flush=True)
+
+    # Build convergence prompt
+    conflict_text = "\n".join(
+        f"- {f}: modified by {o1} and {o2}" for f, o1, o2 in conflicts
+    )
+
+    convergence_prompt = f"""# Convergence Task
+
+Multiple parallel agents modified overlapping files. Resolve any conflicts.
+
+## Conflicts Detected
+{conflict_text}
+
+## Milestones Completed in This Batch
+{chr(10).join(f'- {m.id}: {m.title}' for m in completed_in_batch)}
+
+## Instructions
+1. Read each conflicted file
+2. Check for type mismatches, duplicate definitions, incompatible interfaces
+3. Reconcile into a consistent state
+4. Run `tsc --noEmit` (TypeScript) or equivalent type checker
+5. Fix any remaining build errors
+6. Do NOT add new features - only resolve conflicts between existing code
+
+When all conflicts are resolved and the build is clean, output [DAVELOOP:RESOLVED].
+"""
+
+    # Run convergence via DaveLoop (without Task tool - no swarm for convergence)
+    result = engine.run(convergence_prompt, project_dir, max_iterations=5)
+    if result.resolved:
+        print("[Boris] Convergence: All conflicts resolved", flush=True)
+        logger.info("Convergence phase completed successfully")
+    else:
+        print("[Boris] WARNING: Convergence could not resolve all conflicts", flush=True)
+        logger.warning("Convergence phase did not fully resolve")
+
+
+def _print_swarm_dashboard(project_dir: str, batch_num: int, batch_milestones: list):
+    """Print a swarm status dashboard showing all active workers in the current batch (B7)."""
+    statuses = engine.read_worker_statuses(project_dir)
+    if not statuses:
+        return
+
+    active = sum(1 for s in statuses.values() if s.get("state") in ("starting", "working"))
+    total_actions = sum(s.get("actions", 0) for s in statuses.values())
+
+    print(flush=True)
+    print("=== BORIS SWARM STATUS ===", flush=True)
+    print(f"Batch {batch_num} | Workers: {active} active / {len(statuses)} total | Actions: {total_actions}", flush=True)
+    print(flush=True)
+
+    for m in batch_milestones:
+        status = statuses.get(m.id, {})
+        state = status.get("state", "unknown")
+        actions = status.get("actions", 0)
+        reasoning = status.get("reasoning_blocks", 0)
+        interrupts = status.get("interrupts", 0)
+        last = status.get("last_action", "")
+
+        # Progress indicator based on reasoning blocks (rough proxy)
+        bar_len = min(reasoning, 10)
+        bar = "#" * bar_len + "-" * (10 - bar_len)
+
+        state_str = state.upper()
+        interrupt_str = f" | {interrupts} interrupts" if interrupts > 0 else ""
+        print(f"[{m.id}] {m.title[:30]:<30} [{bar}] {state_str} | {actions} actions{interrupt_str}", flush=True)
+        if last:
+            print(f"      Last: {last}", flush=True)
+
+    # Show file locks if file_lock.py is available
+    try:
+        from file_lock import FileLockManager
+        flm = FileLockManager(project_dir)
+        locks = flm.get_locked_files()
+        if locks:
+            lock_strs = [f"{os.path.basename(f)} ({owner})" for f, owner in locks.items()]
+            print(f"\nFile locks: {', '.join(lock_strs)}", flush=True)
+    except ImportError:
+        pass
+
+    print("===========================", flush=True)
+    print(flush=True)
+
+
+def _apply_preset(args):
+    """Apply a swarm preset to args if specified. Preset implies --swarm."""
+    if not args.preset:
+        return
+    args.swarm = True
+    preset = SWARM_PRESETS[args.preset]
+    # Only override if user didn't explicitly set these
+    if args.swarm_budget == 5:  # default value
+        args.swarm_budget = preset["swarm_budget"]
+    if args.swarm_depth == 1:  # default value
+        args.swarm_depth = preset["swarm_depth"]
+    if args.isolation == "none":  # default value
+        args.isolation = preset.get("isolation", "none")
+    if not args.no_converge:
+        args.no_converge = preset["no_converge"]
+
+
 def main():
     """Main Boris orchestration loop."""
     args = parse_args()
 
+    # Apply swarm preset if specified (implies --swarm)
+    _apply_preset(args)
+
     # --stop-at implies incremental mode
     if args.stop_at:
         args.incremental = True
 
+    # Handle --estimate: resolve the task description from either the flag or positional arg
+    if args.estimate is not None:
+        estimate_task = args.estimate if args.estimate != "__FROM_TASK__" else args.task
+        if not estimate_task:
+            print("[Boris] Error: --estimate requires a task description", flush=True)
+            sys.exit(1)
+        args.task = estimate_task
+
     logger = setup_logging()
 
+    # Initialize token estimator for swarm/turbo mode
+    token_estimator = None
+    if getattr(args, 'swarm', False) or getattr(args, 'max_tokens', None) or getattr(args, 'turbo', False):
+        token_estimator = TokenEstimator(max_tokens=args.max_tokens)
+
     # Create required dirs
     os.makedirs(PLANS_DIR, exist_ok=True)
     os.makedirs(LOGS_DIR, exist_ok=True)
@@ -567,6 +935,9 @@ def main():
 
         print_plan_summary(plan)
 
+        # Prompt user to skip milestones before execution
+        prompt_skip_milestones(plan, logger)
+
         # Create initial state from the loaded plan
         st = state_module.State(
             plan=plan,
@@ -625,10 +996,32 @@ def main():
 
         print_plan_summary(plan)
 
+        # --estimate mode: print token estimate and exit without executing
+        if args.estimate is not None:
+            estimator = TokenEstimator()
+            estimate = estimator.estimate_task(plan)
+            print("=" * 60, flush=True)
+            print("  BORIS - Token Estimate", flush=True)
+            print("=" * 60, flush=True)
+            print(f"  Milestones:          {estimate['num_milestones']}", flush=True)
+            print(f"  Avg iterations each: {estimate['avg_iterations_per_milestone']}", flush=True)
+            print(f"  Tokens/milestone:    {estimate['tokens_per_milestone']:,}", flush=True)
+            print(f"  Milestone tokens:    {estimate['total_milestone_tokens']:,}", flush=True)
+            print(f"  Convergence tokens:  {estimate['convergence_tokens']:,}", flush=True)
+            print(f"  ----------------------------------------", flush=True)
+            print(f"  TOTAL ESTIMATED:     {estimate['total_tokens']:,} tokens", flush=True)
+            print("=" * 60, flush=True)
+            print(flush=True)
+            print("[Boris] Estimate-only mode. No execution performed.", flush=True)
+            return
+
         if args.plan_only:
             print("[Boris] Plan-only mode. Exiting.", flush=True)
             return
 
+        # Prompt user to skip milestones before execution
+        prompt_skip_milestones(plan, logger)
+
         # Create initial state
         st = state_module.State(
             plan=plan,
@@ -686,6 +1079,27 @@ def main():
                             state_module.save(st)
                         break
 
+                    # Dependency-aware batch validation: filter milestones with skipped deps
+                    ready = validate_turbo_batch(ready, plan, logger)
+                    if not ready:
+                        logger.warning("All ready milestones filtered out by turbo batch validation")
+                        break
+
+                    # Foundation-first: first batch only runs milestones with no dependencies
+                    if batch_num == 0:
+                        foundation = [m for m in ready if not m.depends_on]
+                        if foundation:
+                            ready = foundation[:1]  # Only one foundation milestone at a time
+
+                    # Token budget check (swarm/turbo mode)
+                    if token_estimator:
+                        estimated = token_estimator.estimate_batch(len(ready), args.max_iter, args.swarm_budget if getattr(args, 'swarm', False) else 0)
+                        if not token_estimator.check_budget(estimated):
+                            print(f"[Boris] Token budget exceeded. Estimated: {token_estimator.estimated_tokens + estimated:,}, Budget: {token_estimator.max_tokens:,} tokens", flush=True)
+                            logger.warning("Token budget exceeded, stopping execution")
+                            break
+                        token_estimator.record_tokens(estimated)
+
                     batch_num += 1
                     batch_ids = [m.id for m in ready]
                     print(flush=True)
@@ -711,7 +1125,12 @@ def main():
                         prompt_map[m.id] = prompt
 
                     # Run all DaveLoops in parallel
-                    parallel_results = engine.run_parallel(tasks, project_dir, args.max_iter)
+                    isolation = getattr(args, 'isolation', 'none') if getattr(args, 'swarm', False) else 'none'
+                    parallel_results = engine.run_parallel(tasks, project_dir, args.max_iter, isolation=isolation)
+
+                    # Print swarm dashboard after parallel run completes (B7)
+                    _print_swarm_dashboard(project_dir, batch_num, ready)
+                    engine.clear_worker_statuses(project_dir)
 
                     # Process verdicts sequentially (corrections/retries run sequentially)
                     batch_summary = {}
@@ -731,6 +1150,13 @@ def main():
                         )
                         batch_summary[milestone.id] = milestone.status.upper()
 
+                    # Convergence phase: reconcile type conflicts from parallel workers
+                    if not getattr(args, 'no_converge', False):
+                        completed_in_batch = [m for m, r in parallel_results if m.status == "completed"]
+                        if len(completed_in_batch) > 1:
+                            print(f"[Boris] TURBO: Running convergence phase for batch {batch_num}...", flush=True)
+                            _run_convergence(st, plan, project_dir, completed_in_batch, logger)
+
                     # Git commits sequentially after entire batch
                     if not st.no_git:
                         for milestone, result in parallel_results:

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

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

borisxdave-0.3.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+boris.py,sha256=VwVjetw6Tfs397btdCDRuM_iRlPI5XSzqfalqlwSLlA,62940
+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=Sln8ukCby2gWcs_U3ru4YSXCTWI5MgkI4WB4ONLIyWk,34779
+state.py,sha256=2DCPlcM7SBlCkwWvcnIabltcduv74W46FZ7DxKurWkw,5752
+Users/david/AppData/Local/Programs/Python/Python313/Lib/site-packages/boris_prompt.md,sha256=W8bQP4c-iLLtxSsscIxbjXI2PlWTNbOrq05UGp9mLWs,7839
+borisxdave-0.3.1.dist-info/METADATA,sha256=1Q8uBCfA2BpHdmgK-6kwR58ESpChi2JcTsRoLbz2MoU,133
+borisxdave-0.3.1.dist-info/WHEEL,sha256=hPN0AlP2dZM_3ZJZWP4WooepkmU9wzjGgCLCeFjkHLA,92
+borisxdave-0.3.1.dist-info/entry_points.txt,sha256=a6FLWgxiQjGMJIRSV5sDxaaaaQchunm04ZuzX8N7-6I,61
+borisxdave-0.3.1.dist-info/top_level.txt,sha256=GSKxzJ_M15C-hpRGaC1C5pusFxA1JIaxaSHYaLg4rQc,64
+borisxdave-0.3.1.dist-info/RECORD,,

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

@@ -1,6 +1,7 @@
 boris
 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

prompts.py

@@ -29,17 +29,32 @@ _boris_prompt_cache = None
 
 
 def _load_boris_prompt() -> str:
-    """Load Boris's management prompt from boris_prompt.md. Cached after first load."""
+    """Load Boris's management prompt from boris_prompt.md. Cached after first load.
+
+    Searches multiple locations to handle both editable installs (source dir)
+    and regular pip installs (site-packages).
+    """
     global _boris_prompt_cache
     if _boris_prompt_cache is not None:
         return _boris_prompt_cache
-    try:
-        with open(_BORIS_PROMPT_PATH, "r", encoding="utf-8") as f:
-            _boris_prompt_cache = f.read().strip()
-        logger.debug("Loaded Boris prompt: %d chars", len(_boris_prompt_cache))
-    except FileNotFoundError:
-        logger.warning("boris_prompt.md not found at %s", _BORIS_PROMPT_PATH)
-        _boris_prompt_cache = ""
+
+    search_paths = [
+        _BORIS_PROMPT_PATH,  # Next to this .py file (editable install / source)
+        os.path.join(sys.prefix, "boris_prompt.md"),  # sys.prefix (some data_files installs)
+        os.path.join(os.path.dirname(shutil.which("boris") or ""), "boris_prompt.md"),  # Next to boris script
+    ]
+
+    for path in search_paths:
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                _boris_prompt_cache = f.read().strip()
+            logger.debug("Loaded Boris prompt from %s (%d chars)", path, len(_boris_prompt_cache))
+            return _boris_prompt_cache
+        except (FileNotFoundError, OSError, TypeError):
+            continue
+
+    logger.warning("boris_prompt.md not found in any search path: %s", search_paths)
+    _boris_prompt_cache = ""
     return _boris_prompt_cache
 
 # Regex to strip ANSI escape codes

state.py

@@ -67,13 +67,92 @@ class State:
 
 
 def save(state: State) -> None:
-    """Save state to {project_dir}/.boris/state.json."""
+    """Save state to {project_dir}/.boris/state.json and plan.md."""
     state_dir = os.path.join(state.project_dir, config.STATE_DIR)
     os.makedirs(state_dir, exist_ok=True)
     state_path = os.path.join(state_dir, config.STATE_FILE)
     state.updated_at = datetime.now().isoformat()
     with open(state_path, "w", encoding="utf-8") as f:
         json.dump(asdict(state), f, indent=2, ensure_ascii=False)
+    # Also export a human-readable markdown plan
+    _save_plan_md(state)
+
+
+def _save_plan_md(state: State) -> None:
+    """Export the plan as a readable markdown file in the project directory."""
+    plan = state.plan
+    if not plan or not plan.milestones:
+        return
+
+    status_icon = {
+        "completed": "[x]",
+        "in_progress": "[-]",
+        "skipped": "[~]",
+        "pending": "[ ]",
+    }
+
+    lines = []
+    lines.append(f"# Boris Plan")
+    lines.append("")
+    lines.append(f"**Task:** {plan.task}")
+    lines.append(f"**Created:** {plan.created_at}")
+    lines.append(f"**Updated:** {state.updated_at}")
+    lines.append(f"**Mode:** {'Turbo (parallel)' if state.turbo else 'Sequential'}")
+    lines.append("")
+
+    # Summary counts
+    counts = {}
+    for m in plan.milestones:
+        counts[m.status] = counts.get(m.status, 0) + 1
+    total = len(plan.milestones)
+    done = counts.get("completed", 0)
+    lines.append(f"**Progress:** {done}/{total} milestones completed")
+    if counts.get("skipped", 0):
+        lines.append(f"**Skipped:** {counts['skipped']}")
+    lines.append("")
+    lines.append("---")
+    lines.append("")
+
+    # Milestone list
+    lines.append("## Milestones")
+    lines.append("")
+    for m in plan.milestones:
+        icon = status_icon.get(m.status, "[ ]")
+        lines.append(f"### {icon} {m.id}: {m.title}")
+        lines.append("")
+        if m.depends_on:
+            lines.append(f"**Depends on:** {', '.join(m.depends_on)}")
+        lines.append(f"**Status:** {m.status}")
+        if m.completed_at:
+            lines.append(f"**Completed:** {m.completed_at}")
+        lines.append("")
+        lines.append(m.description)
+        lines.append("")
+
+        if m.acceptance_criteria:
+            lines.append("**Acceptance Criteria:**")
+            for ac in m.acceptance_criteria:
+                lines.append(f"- {ac}")
+            lines.append("")
+
+        if m.files_to_create:
+            lines.append(f"**Files to create:** {len(m.files_to_create)}")
+            for f_path in m.files_to_create:
+                lines.append(f"- `{f_path}`")
+            lines.append("")
+
+        if m.files_to_modify:
+            lines.append(f"**Files to modify:** {len(m.files_to_modify)}")
+            for f_path in m.files_to_modify:
+                lines.append(f"- `{f_path}`")
+            lines.append("")
+
+        lines.append("---")
+        lines.append("")
+
+    md_path = os.path.join(state.project_dir, config.STATE_DIR, "plan.md")
+    with open(md_path, "w", encoding="utf-8") as f:
+        f.write("\n".join(lines))
 
 
 def load(project_dir: str) -> Optional[State]:

borisxdave-0.3.0.dist-info/RECORD

@@ -1,12 +0,0 @@
-boris.py,sha256=xStvDOxKqbvQiNsQORr4qcD5wEiruNIcm7v_fFPjwZ8,44667
-config.py,sha256=KfFKyCGasdm1yBvIRFv-ykzA_oRo-zu1Euu9YC7V1Cg,324
-engine.py,sha256=LuVUwtlE1j8K3MOIH_pozB6Vy04_kPJs7Q0l9g-ePa8,27875
-git_manager.py,sha256=BuuTT4naPb5-jLhOik1xHM2ztzuKvJ_bnecZmlYgwFs,8493
-planner.py,sha256=UrU--kBvzvyD1gOVxIn-kdbJiu8tt4rcowsln66WkGw,5670
-prompts.py,sha256=oBVDZ0dG50FcSBa4F9GTkCPxmMB653BsK3RShoGcWUM,34182
-state.py,sha256=8MeUiDwL9ecgD9N6RhNUQf_P-qE7HeG3WlgL_SbRQic,3160
-borisxdave-0.3.0.dist-info/METADATA,sha256=qP3P-mpjm-BaQuJBXasveJ4L_wGNH9S-pIhNLAdNVd4,133
-borisxdave-0.3.0.dist-info/WHEEL,sha256=hPN0AlP2dZM_3ZJZWP4WooepkmU9wzjGgCLCeFjkHLA,92
-borisxdave-0.3.0.dist-info/entry_points.txt,sha256=a6FLWgxiQjGMJIRSV5sDxaaaaQchunm04ZuzX8N7-6I,61
-borisxdave-0.3.0.dist-info/top_level.txt,sha256=zNzzkbLJWzWpTjJTQsnbdOBypcA4XpioE1dEgWZVBx4,54
-borisxdave-0.3.0.dist-info/RECORD,,