misterdev 0.2.0__py3-none-any.whl

misterdev/agent.py

@@ -0,0 +1,2166 @@
+import concurrent.futures
+import re
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.prompt import Prompt
+
+from misterdev.core.execution.registry import ProjectRegistry
+from misterdev.core.modes import (
+    BuildMode,
+    BuildFlags,
+    parse_flags,
+    resolve_mode,
+)
+from misterdev.core.planning.assessment import (
+    ProjectAssessment,
+    HealthCheck,
+)
+from misterdev.core.context.scratchpad import Scratchpad
+from misterdev.core.planning.decomposer import (
+    decompose_spec,
+    topological_sort,
+    format_plan,
+)
+from misterdev.core.verification.validator import ValidationResult
+from misterdev.core.verification.gatekeeper import GateKeeper
+from misterdev.core.gitcmd import run_git
+from misterdev.core.planning.sovereign import (
+    StrategyOptimizer,
+    RealTimeAligner,
+    ABMCTSPlanner,
+    EphemeralCodeManager,
+    ProbeGenerator,
+)
+from misterdev.core.planning.metacognition import SessionAuditor
+from misterdev.core.context.contracts import ContractRegistry
+from misterdev.core.verification.preflight import PreflightValidator
+from misterdev.core.execution.progress import (
+    ProgressTracker,
+    compute_task_hash,
+)
+from misterdev.core.context.change_tracker import ChangeTracker
+from misterdev.core.reporting.report import BuildReport
+from misterdev.core.execution.project import Project
+from misterdev.core.models import Task
+from misterdev.analyzers.project_analyzer import (
+    analyze_project,
+)
+from misterdev.core.planning.advisor import recommend_work
+from misterdev.llm.client import BudgetExceededError
+from misterdev.task_executors.markdown_plan_executor import (
+    MarkdownPlanExecutor,
+)
+from misterdev.agent_helpers import (
+    ProgressReporter,
+    _WorktreeProjectView,
+    _apply_budget_ceiling,
+    _budget_exhausted,
+    _check_golden_config,
+    _combine_commands,
+    _warn_if_baseline_broken,
+    _warn_if_no_test_gate,
+)
+from misterdev.config import get_setting
+from misterdev.logging_setup import setup_logger
+
+logger = setup_logger(__name__)
+console = Console()
+
+MAX_CONSECUTIVE_FAILURES = 3
+
+# Safety backstop for "auto" convergence: the loop normally stops earlier on a
+# green gate, budget exhaustion, or no-progress, but this bounds a pathological
+# run that keeps producing genuinely different (yet still failing) fix tasks.
+CONVERGENCE_CEILING = 25
+
+
+class ProjectOrchestrator:
+    """Main orchestrator with Sovereign Grounded workflow."""
+
+    def __init__(self):
+        self.registry = ProjectRegistry()
+        self.last_build_succeeded = True
+
+    def scan_directory(self, path: str | Path):
+        self.registry.discover_projects(path)
+
+    def list_projects(self) -> Dict[str, Any]:
+        return self.registry.list_projects()
+
+    def get_project_status(self, project_path: str | Path) -> Dict[str, Any]:
+        project = self.registry.get_project(project_path)
+        if not project:
+            try:
+                project = self.registry.register_project(project_path)
+            except Exception as e:
+                logger.error(f"Failed to load project at {project_path}: {e}")
+                return {"error": f"Project load failed: {e}"}
+        project.task_manager.discover_tasks()
+        return {
+            "name": project.name,
+            "path": str(project.path),
+            "description": project.description,
+            "tasks": [
+                {"id": t.id, "status": t.status, "description": t.description[:100]}
+                for t in project.task_manager.tasks.values()
+            ],
+        }
+
+    def run_project(
+        self,
+        project_path: str | Path,
+        dry_run: bool = False,
+        skip_preflight: bool = False,
+        force: bool = False,
+        status: bool = False,
+    ):
+        """Run pending devplan tasks with dependency-aware orchestration.
+
+        Unlike build(), this executes a pre-written devplan: it skips the
+        analysis/spec/decomposition/gate phases but adds topological
+        ordering, progress-based crash recovery, contract injection, scratchpad
+        learning, and change tracking around the existing markdown tasks.
+        """
+        project = self._get_or_register(project_path)
+        if not project:
+            return
+        _check_golden_config(project.config)
+        if project.env_manager:
+            project.env_manager.setup()
+        project.task_manager.discover_tasks()
+        pending = project.task_manager.get_pending_tasks()
+        if not pending:
+            logger.info(f"No pending tasks for {project.name}.")
+            return
+        tasks = topological_sort(pending)
+
+        if not skip_preflight:
+            issues = PreflightValidator().validate(tasks, project.path)
+            for issue in issues:
+                log = logger.error if issue.severity == "error" else logger.warning
+                log(f"Preflight {issue.severity}: {issue.task_id}: {issue.message}")
+            if PreflightValidator.has_errors(issues):
+                logger.error(
+                    "Preflight validation failed; aborting. Use --skip-preflight to override."
+                )
+                return
+
+        if dry_run:
+            self._print_execution_plan(tasks)
+            return
+
+        if status:
+            self._print_rerun_status(
+                tasks, ProgressTracker(project.path), project.path, force
+            )
+            return
+
+        scratchpad = Scratchpad()
+        contracts = ContractRegistry(project.path)
+        progress = ProgressTracker(project.path)
+        changes = ChangeTracker(project.path)
+        strategy_optimizer = StrategyOptimizer()
+        executor = MarkdownPlanExecutor(scratchpad=scratchpad)
+        lang = (project.config.get("language") or "python").lower()
+        max_consecutive_failures = get_setting(
+            project.config, "orchestrator", "max_consecutive_failures"
+        )
+
+        completed_ids = set(progress.completed)
+        failed_ids: set[str] = set()
+        consecutive_failures = 0
+        if completed_ids:
+            logger.info(f"Resuming run: {len(completed_ids)} tasks already completed")
+        logger.info(f"Running {len(tasks)} pending tasks for {project.name}.")
+
+        reporter = ProgressReporter(len(tasks))
+        remaining = list(tasks)
+        aborted = False
+        wave = 0
+        while remaining and not aborted:
+            ready, still_waiting = [], []
+            for task in remaining:
+                if not force and not progress.needs_rerun(
+                    task.id, compute_task_hash(task, project.path)
+                ):
+                    completed_ids.add(task.id)
+                    continue
+                if progress.is_done(task.id):
+                    logger.info(
+                        f"Task {task.id} previously completed but inputs changed; re-running."
+                    )
+                if any(d in failed_ids for d in task.dependencies):
+                    failed_ids.add(task.id)
+                    logger.warning(f"Skipping {task.id}: a dependency failed.")
+                    continue
+                if any(d not in completed_ids for d in task.dependencies):
+                    still_waiting.append(task)
+                    continue
+                ready.append(task)
+
+            if not ready:
+                if still_waiting:
+                    logger.error(
+                        f"Dependency deadlock; unresolved tasks: {[t.id for t in still_waiting]}"
+                    )
+                break
+
+            wave += 1
+            reporter.start_wave(wave, [t.id for t in ready])
+            for task in ready:
+                reporter.start_task(task.id, task.title or task.description[:50])
+                try:
+                    self._inject_task_context(
+                        task, contracts, changes, strategy_optimizer, project
+                    )
+                    result = executor.execute(task, project)
+                    task.execution_history.append(result)
+                except BudgetExceededError as e:
+                    # Terminal (budget spent or account out of credits): stop the
+                    # whole run cleanly rather than crash or churn the next tasks.
+                    logger.warning(f"Halting run: {e}")
+                    aborted = True
+                    break
+                except Exception as e:
+                    logger.error(f"Task {task.id} raised: {e}")
+                    result = None
+
+                succeeded = result is not None and result.status == "completed"
+                reporter.end_task(task.id, succeeded)
+                if succeeded:
+                    completed_ids.add(task.id)
+                    progress.mark_completed(
+                        task.id, compute_task_hash(task, project.path)
+                    )
+                    consecutive_failures = 0
+                    modified = task.files_to_modify + task.files_to_create
+                    if modified:
+                        contracts.extract_contracts(
+                            task.id,
+                            modified,
+                            project.path,
+                            project.llm_client,
+                            language=lang,
+                        )
+                        changes.record_task_changes(task.id, modified)
+                else:
+                    failed_ids.add(task.id)
+                    progress.mark_failed(task.id)
+                    consecutive_failures += 1
+                    if consecutive_failures >= max_consecutive_failures:
+                        logger.error("Aborting run: too many consecutive failures.")
+                        aborted = True
+                        break
+
+            remaining = still_waiting
+
+        reporter.summary()
+
+    def _inject_task_context(
+        self, task, contracts, changes, strategy_optimizer, project
+    ) -> None:
+        """Populate a task's processor_data with contracts, recent changes, and strategy."""
+        task.processor_data["interface_contracts"] = contracts.get_contracts_for_task(
+            task.dependencies
+        )
+        task.processor_data["recent_changes"] = changes.get_recent_changes_for_files(
+            task.files_to_modify + task.files_to_create
+        )
+        task.processor_data["strategy"] = strategy_optimizer.select_best_strategy(
+            task.description, task.category, "", project.llm_client
+        )
+
+    def _print_execution_plan(self, tasks: list[Task]) -> None:
+        """Print the dependency-ordered wave plan without executing anything."""
+        completed: set[str] = set()
+        remaining = list(tasks)
+        wave = 0
+        console.print(f"\n[bold]Execution Plan (dry-run): {len(tasks)} tasks[/]")
+        while remaining:
+            ready = [
+                t for t in remaining if all(d in completed for d in t.dependencies)
+            ]
+            if not ready:
+                console.print(
+                    f"[red]Dependency deadlock among: {[t.id for t in remaining]}[/]"
+                )
+                break
+            wave += 1
+            console.print(f"\n[bold cyan]Wave {wave}[/] ({len(ready)} parallel):")
+            for t in ready:
+                deps = f" -> depends on {t.dependencies}" if t.dependencies else ""
+                console.print(
+                    f"  [{t.id}] {t.title or t.description[:50]} ({t.complexity}, {t.category}){deps}"
+                )
+                completed.add(t.id)
+            remaining = [t for t in remaining if t.id not in completed]
+        console.print(f"\n[dim]Total: {len(tasks)} tasks, {wave} waves.[/]\n")
+
+    def _print_rerun_status(
+        self, tasks: list[Task], progress, project_path, force: bool
+    ) -> None:
+        """Show which tasks would run vs skip, based on content hashes."""
+        console.print(f"\n[bold]Task status: {len(tasks)} tasks[/]")
+        run = 0
+        for t in tasks:
+            rerun = force or progress.needs_rerun(
+                t.id, compute_task_hash(t, project_path)
+            )
+            if rerun:
+                run += 1
+                reason = (
+                    "forced"
+                    if force
+                    else ("changed" if progress.is_done(t.id) else "pending")
+                )
+                console.print(f"  [yellow]RUN [/] {t.id}  ({reason})")
+            else:
+                console.print(f"  [green]SKIP[/] {t.id}  (unchanged, completed)")
+        console.print(f"\n[dim]{run} would run, {len(tasks) - run} would skip.[/]\n")
+
+    def run_task(self, project_path: str | Path, task_id: str):
+        """Runs a specific task for a given project."""
+        project = self._get_or_register(project_path)
+        if not project:
+            return
+        if project.env_manager:
+            project.env_manager.setup()
+        project.task_manager.discover_tasks()
+        task = project.task_manager.tasks.get(task_id)
+        if not task:
+            logger.error(f"Task {task_id} not found in {project.name}.")
+            return
+        # Inject contracts from this task's already-completed dependencies.
+        contracts = ContractRegistry(project.path)
+        task.processor_data["interface_contracts"] = contracts.get_contracts_for_task(
+            task.dependencies
+        )
+        executor = MarkdownPlanExecutor()
+        try:
+            result = executor.execute(task, project)
+            task.execution_history.append(result)
+        except Exception as e:
+            logger.error(f"Task {task_id} raised: {e}")
+            project.task_manager.update_task_status(task_id, "failed")
+
+    def build(self, project_path: str | Path, args: str = "") -> str:
+        project = self._get_or_register(project_path)
+        if not project:
+            return "Error: could not load project"
+
+        arg_list = args.split() if args else []
+        remaining, flags = parse_flags(arg_list)
+        prompt = " ".join(remaining)
+        mode = resolve_mode(prompt, project.path)
+
+        logger.info(f"Build started: mode={mode.value}, flags={flags}")
+        start_time = datetime.now(timezone.utc)
+
+        # Refuse to run on a dirty working tree: branch-per-task execution
+        # carries and can sweep/revert uncommitted changes, so a second writer
+        # (or the user's own in-progress work) would be corrupted. Override with
+        # --allow-dirty. Skipped for dry-run (read-only).
+        if not flags.dry_run and not flags.allow_dirty:
+            dirty = self._working_tree_dirty(project)
+            if dirty:
+                logger.error("Refusing to build on a dirty working tree.")
+                return (
+                    f"Error: working tree has uncommitted changes ({dirty}). "
+                    "Commit or stash them first, or pass --allow-dirty to override."
+                )
+
+        # Propagate budget to LLM client
+        _apply_budget_ceiling(project.llm_client, flags.budget)
+
+        # Preflight: fail fast on a retired/misrouted model id before spending
+        # the analysis phase on calls that would 404 mid-run.
+        if not flags.dry_run:
+            ok, detail = project.llm_client.health_check()
+            if not ok:
+                logger.error(f"Model preflight failed: {detail}")
+                return f"Error: {detail}. Set a valid model in config before building."
+
+        env_activate = self._setup_env(project)
+
+        # The budget ceiling is a graceful kill-switch, not a crash: a
+        # BudgetExceededError can surface from ANY model call (an analysis
+        # analyzer, probe discovery, spec generation, decomposition, or a task),
+        # so wrap the whole pipeline and degrade to a partial report instead of
+        # letting the CLI die with a traceback. (Found by dogfooding: a $2 cap was
+        # exhausted by pre-execution analysis+probes+spec and crashed the run.)
+        report = None
+        try:
+            # Phase 1: Analysis
+            assessment = self._analyze(project, env_activate)
+
+            report = BuildReport(mode, project.name, assessment, start_time)
+            report.health_before = assessment.health.model_copy()
+            _warn_if_baseline_broken(assessment, report)
+            _warn_if_no_test_gate(assessment, project, report)
+
+            return self._run_pipeline(
+                project, prompt, mode, flags, assessment, env_activate, report
+            )
+        except BudgetExceededError as e:
+            return self._halt_on_budget(project, report, e)
+
+    def _halt_on_budget(
+        self, project: Project, report: Optional[BuildReport], error: Exception
+    ) -> str:
+        """Degrade a budget-exhausted run to a partial report (never a traceback).
+
+        Records the halt, finalizes whatever work completed, and returns the
+        report markdown. When the cap is hit before the report exists (during
+        analysis), returns a concise message instead.
+        """
+        self.last_build_succeeded = False
+        logger.error(f"Build halted by budget ceiling: {error}")
+        if report is None:
+            return (
+                f"Build halted: {error}. The budget ceiling stopped the run during "
+                "analysis, before any task executed. Raise --budget to proceed."
+            )
+        report.key_decisions.append(f"Halted by budget ceiling: {error}")
+        report.finalize()
+        usage = project.llm_client.cumulative_usage
+        report.llm_calls = usage.call_count
+        report.llm_tokens = usage.total_tokens
+        report.llm_prompt_tokens = getattr(usage, "prompt_tokens", 0)
+        report.llm_completion_tokens = getattr(usage, "completion_tokens", 0)
+        report.llm_cache_read_tokens = getattr(usage, "cache_read_tokens", 0)
+        report.llm_cost = usage.estimated_cost
+        report.save(project.path)
+        return report.to_markdown()
+
+    def interactive_plan(self, project_path: str | Path, args: str = "") -> str:
+        """Analyze the project, recommend work, and compose a plan with the user.
+
+        The entry point for a plain `misterdev` invocation: instead
+        of a predefined devplan, it reads the live project state, proposes
+        ranked work items, lets the user choose (or type their own goal), then
+        composes and confirms the plan before executing.
+        """
+        project = self._get_or_register(project_path)
+        if not project:
+            return "Error: could not load project"
+
+        _, flags = parse_flags(args.split() if args else [])
+        start_time = datetime.now(timezone.utc)
+        _apply_budget_ceiling(project.llm_client, flags.budget)
+
+        if not flags.allow_dirty:
+            dirty = self._working_tree_dirty(project)
+            if dirty:
+                console.print(
+                    f"[red]Working tree has uncommitted changes ({dirty}).[/] "
+                    "Commit or stash first, or pass --allow-dirty."
+                )
+                return f"Error: dirty working tree ({dirty})."
+
+        ok, detail = project.llm_client.health_check()
+        if not ok:
+            console.print(f"[red]Model preflight failed:[/] {detail}")
+            return f"Error: {detail}. Set a valid model in config before building."
+
+        env_activate = self._setup_env(project)
+
+        report = None
+        try:
+            console.print(f"[bold]Analyzing[/] {project.name} ...")
+            assessment = self._analyze(project, env_activate)
+            console.print(
+                Panel(assessment.summary(), title="Current state", expand=False)
+            )
+
+            recs = recommend_work(assessment, project.llm_client)
+            goal, mode = self._choose_goal(recs)
+            if goal is None:
+                return "Cancelled: no work selected."
+
+            report = BuildReport(mode, project.name, assessment, start_time)
+            report.health_before = assessment.health.model_copy()
+            _warn_if_baseline_broken(assessment, report)
+            _warn_if_no_test_gate(assessment, project, report)
+            return self._run_pipeline(
+                project,
+                goal,
+                mode,
+                flags,
+                assessment,
+                env_activate,
+                report,
+                confirm_plan=True,
+            )
+        except BudgetExceededError as e:
+            return self._halt_on_budget(project, report, e)
+
+    def _choose_goal(self, recs: list) -> tuple[Optional[str], BuildMode]:
+        """Present recommendations and return the chosen (goal, mode).
+
+        Returns (None, _) if the user quits. A free-text goal resolves its own
+        mode; a picked recommendation carries the advisor's work_type.
+        """
+        if recs:
+            console.print("\n[bold]Recommended work:[/]")
+            for i, r in enumerate(recs, 1):
+                console.print(
+                    f"  [cyan]{i}[/]. {r.title} [dim]({r.work_type}) — {r.rationale}[/]"
+                )
+        console.print("\nEnter a number to pick, type your own goal, or 'q' to quit.")
+        choice = Prompt.ask("Goal").strip()
+        if not choice or choice.lower() in ("q", "quit"):
+            return None, BuildMode.SMART
+        if choice.isdigit() and recs:
+            idx = int(choice) - 1
+            if 0 <= idx < len(recs):
+                r = recs[idx]
+                return r.title, self._WORK_TYPE_MODES.get(r.work_type, BuildMode.SMART)
+            console.print("[yellow]Out of range; treating input as a goal.[/]")
+        return choice, resolve_mode(choice, Path("."))
+
+    _WORK_TYPE_MODES = {
+        "debug": BuildMode.DEBUG,
+        "complete": BuildMode.COMPLETE,
+        "feature": BuildMode.SMART,
+        "refactor": BuildMode.SMART,
+        "test": BuildMode.SMART,
+        "docs": BuildMode.SMART,
+    }
+
+    def _confirm(self, question: str) -> bool:
+        """Ask a yes/no question; defaults to no."""
+        return Prompt.ask(f"{question} [y/N]", default="n").strip().lower() in (
+            "y",
+            "yes",
+        )
+
+    def _working_tree_dirty(self, project: Project) -> str:
+        """Return a short summary if the git working tree has uncommitted changes.
+
+        Returns "" when clean or not a git repo. `git status --porcelain`
+        already excludes ignored paths, so the orchestrator's own `.orchestrator/`
+        cache (gitignored) never counts as dirty.
+        """
+        if not (Path(project.path) / ".git").exists():
+            return ""
+        try:
+            proc = subprocess.run(
+                ["git", "status", "--porcelain"],
+                cwd=project.path,
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+        except (subprocess.SubprocessError, OSError) as e:
+            logger.warning(f"Could not check working tree status: {e}")
+            return ""
+        lines = [ln for ln in proc.stdout.splitlines() if ln.strip()]
+        if not lines:
+            return ""
+        return f"{len(lines)} file(s), e.g. {lines[0][3:].strip()}"
+
+    def _run_pipeline(
+        self,
+        project: Project,
+        prompt: str,
+        mode: BuildMode,
+        flags: BuildFlags,
+        assessment: ProjectAssessment,
+        env_activate: Optional[str],
+        report: BuildReport,
+        confirm_plan: bool = False,
+    ) -> str:
+        """Phases 1.5-6: probes, spec, decompose, (confirm), execute, validate.
+
+        Shared by build() and interactive_plan(). When confirm_plan is set, the
+        composed plan is shown and the user is asked to approve it before any
+        task executes.
+        """
+        _check_golden_config(project.config)
+        # Make the analysis baseline failure count available to the per-task test
+        # gate so a RED baseline doesn't reject every task: the gate then accepts a
+        # task that leaves the suite no worse, letting a multi-failure project be
+        # fixed incrementally. 0 on a green/unknown baseline keeps the gate strict.
+        project.baseline_test_failures = int(
+            getattr(assessment.health, "test_failures", 0) or 0
+        )
+        # Also surface the baseline failure OUTPUT so a fix task can see the real
+        # failures on its FIRST attempt (instead of editing blind and only learning
+        # what broke on retry). Empty on a green baseline.
+        project.baseline_test_output = (
+            getattr(assessment.health, "test_output", "") or ""
+            if project.baseline_test_failures
+            else ""
+        )
+        # Record the pre-build HEAD so the optional goal-completion check can diff
+        # the whole build's work (committed task commits + working tree) against
+        # it. Best-effort: None outside a git repo or on error, which the check
+        # treats as "no diff" and degrades to a summary-only judgment.
+        goal_check_base = self._capture_head(project)
+        # Spec-as-tests, when enabled, is wired per-task in the executor: the
+        # generated failing test is written under .orchestrator/spec_tests/
+        # (outside the project suite, so it never flips the integration-gate
+        # baseline) and run scoped after the task's own gates pass. Nothing to do
+        # at the pipeline level.
+        # Sovereign Phase 1.5: Empirical Probes (only for SMART/CREATE modes).
+        # Best-effort: probe discovery must never crash the build, so any
+        # failure here degrades to no verified facts rather than aborting. Opt out
+        # via orchestrator.enable_probes for a cheaper/faster run (probes spend an
+        # LLM call plus ephemeral script runs before any task executes).
+        verified_facts = ""
+        probes_on = get_setting(project.config, "orchestrator", "enable_probes")
+        if probes_on and mode in (BuildMode.SMART, BuildMode.CREATE):
+            logger.info("Phase 1.5: Empirical Probe Discovery")
+            try:
+                probe_gen = ProbeGenerator(project.llm_client)
+                with EphemeralCodeManager(project.path) as ephemeral:
+                    probes = probe_gen.generate_probes(prompt, assessment.summary())
+                    probe_findings = []
+                    for p in probes:
+                        success, output = ephemeral.run_ephemeral_script(
+                            p.get("script", ""),
+                            name=f"probe_{p.get('name', 'unknown')}",
+                        )
+                        probe_findings.append(
+                            f"Probe: {p.get('name', '?')} -> {output}"
+                        )
+                    verified_facts = "\n".join(probe_findings)
+            except Exception as e:
+                logger.warning(f"Probe discovery failed (non-fatal): {e}")
+                report.degraded_subsystems.append(f"Empirical probes: {e}")
+
+        # Verify completeness claims against the real source before they shape the
+        # spec or the task list, so deliberate design (graceful-degradation,
+        # platform no-ops, parity shims) is not planned as work. Best-effort and
+        # conservative: only claims the verifier refutes with evidence are dropped.
+        self._verify_completeness_claims(project, assessment, report)
+
+        # Phase 2: Generate Spec
+        spec = self._generate_spec(
+            mode, prompt, assessment, project, facts=verified_facts
+        )
+
+        # Sovereign enhancements (metacognition, AB-MCTS) are best-effort: they
+        # refine the spec but must not crash the build, so each degrades to the
+        # current spec on failure rather than aborting before any work is done.
+        auditor = SessionAuditor(project.path, project.llm_client)
+        try:
+            lessons = auditor.get_lessons_context()
+            if lessons:
+                spec = f"{lessons}\n\n{spec}"
+        except Exception as e:
+            logger.warning(f"Lesson injection failed (non-fatal): {e}")
+            report.degraded_subsystems.append(f"Lesson injection: {e}")
+
+        # AB-MCTS branch-and-evaluate is off by default: it fires several serial
+        # LLM calls before any work begins (observed ~30 min on one build) for
+        # marginal spec refinement. Opt in with orchestrator.enable_ab_mcts.
+        if get_setting(project.config, "orchestrator", "enable_ab_mcts"):
+            try:
+                planner = ABMCTSPlanner(project.llm_client)
+                spec = planner.branch_and_evaluate(spec, assessment.summary())
+            except Exception as e:
+                logger.warning(f"AB-MCTS planning failed (non-fatal): {e}")
+                report.degraded_subsystems.append(f"AB-MCTS planning: {e}")
+
+        # Phase 3: Decompose
+        max_tasks = get_setting(project.config, "build", "max_tasks")
+        # A --max-tasks flag is a per-run ceiling: the tighter of it and the
+        # config cap wins, so a focused/bounded run can't balloon into dozens of
+        # tasks (and exhaust the budget) the way a broad spec otherwise would.
+        if isinstance(flags.max_tasks, int) and flags.max_tasks > 0:
+            max_tasks = min(max_tasks, flags.max_tasks)
+        # The decomposer otherwise guesses file paths from feature/test names and
+        # the executor then CREATES a wrong new file. Feed it the real file+symbol
+        # map so a task targets the actual file that defines the code to change.
+        file_map = self._project_file_map(project)
+        targets = self._resolve_targets(project)
+        tasks = decompose_spec(
+            spec,
+            assessment,
+            mode,
+            project.llm_client,
+            str(project.path),
+            max_tasks=max_tasks,
+            file_map=file_map,
+            targets=targets,
+        )
+        tasks = topological_sort(tasks)
+
+        if flags.dry_run:
+            return format_plan(tasks, mode)
+
+        if confirm_plan:
+            console.print(Markdown(format_plan(tasks, mode)))
+            if not self._confirm(f"Proceed with these {len(tasks)} tasks?"):
+                return "Cancelled: plan not approved."
+
+        # Phases 4-5: Execute + Gate, wrapped in an outer convergence loop.
+        # The loop keeps re-attempting concrete gate failures until the gate is
+        # green, the budget runs out, or an iteration makes no progress. The
+        # default "auto" is budget-driven: it runs up to CONVERGENCE_CEILING but
+        # in practice stops on the budget/no-progress guards below. An explicit
+        # positive int caps the iterations hard instead.
+        raw_iterations = get_setting(
+            project.config, "orchestrator", "max_build_iterations"
+        )
+        if (
+            isinstance(raw_iterations, int)
+            and not isinstance(raw_iterations, bool)
+            and raw_iterations > 0
+        ):
+            max_build_iterations = raw_iterations
+        else:
+            max_build_iterations = CONVERGENCE_CEILING
+        iteration = 0
+        prev_issues: Optional[list[str]] = None
+        while True:
+            iteration += 1
+            tasks_this_iter = len(tasks)
+
+            # Phase 4: Execution
+            self._execute_tasks(tasks, project, flags, report)
+
+            # Phase 5: Gates
+            if flags.no_verify:
+                # No gate to converge on; preserve single-pass behavior.
+                break
+            gatekeeper = GateKeeper(
+                project.path,
+                env_activate=env_activate,
+                build_timeout=get_setting(project.config, "build", "build_timeout"),
+                test_timeout=get_setting(project.config, "build", "test_timeout"),
+                lint_timeout=get_setting(project.config, "build", "lint_timeout"),
+                lsp_diagnostics=get_setting(
+                    project.config, "orchestrator", "lsp_diagnostics"
+                ),
+                lsp_language=project.config.get("language"),
+                lsp_timeout=get_setting(project.config, "orchestrator", "lsp_timeout"),
+                container=self._container_engine(project),
+                mutation_gate=get_setting(
+                    project.config, "orchestrator", "mutation_gate"
+                ),
+                mutation_config=project.config.get("mutation") or {},
+                runtime_smoke=get_setting(
+                    project.config, "orchestrator", "runtime_smoke"
+                ),
+                runtime_config=project.config.get("runtime") or {},
+                web_verify=get_setting(project.config, "orchestrator", "web_verify"),
+                vision_verify=get_setting(
+                    project.config, "orchestrator", "vision_verify"
+                ),
+                vision_client=project.llm_client,
+            )
+            commands = {
+                "build_command": assessment.structure.build_command,
+                "test_command": assessment.structure.test_command,
+                "lint_command": assessment.structure.lint_command,
+                "golden_command": get_setting(
+                    project.config, "orchestrator", "golden_command"
+                ),
+            }
+            success, issues, final_health = gatekeeper.run_gates(commands)
+            validation = ValidationResult()
+            validation.build_ok = final_health.builds
+            validation.tests_ok = final_health.tests_pass
+            validation.lint_ok = final_health.lint_clean
+            validation.build_ran = bool(commands["build_command"])
+            validation.tests_ran = bool(commands["test_command"])
+            validation.lint_ran = bool(commands["lint_command"])
+            # Per-target validation: verify EVERY declared sub-project with its
+            # own toolchain. A target failure fails the run even if the top-level
+            # gate was green (no-op when no targets are declared).
+            target_results = self._validate_targets(project, env_activate)
+            if target_results:
+                summary = ", ".join(
+                    f"{r['name']}={'OK' if r['ok'] else 'FAIL'}" for r in target_results
+                )
+                report.key_decisions.append(f"Per-target validation: {summary}")
+                failed_targets = [r["name"] for r in target_results if not r["ok"]]
+                if failed_targets:
+                    issues = list(issues) + [
+                        f"Target validation failed: {', '.join(failed_targets)}"
+                    ]
+                    validation.issues = issues
+                    success = False
+            report.validation = validation
+            report.validation_passed = success
+            report.health_after = final_health
+            self.last_build_succeeded = success
+            if success:
+                break
+            logger.warning(f"Validation failed: {issues}")
+            self._maybe_rollback_regression(project, report, assessment, flags)
+
+            # Decide whether to attempt another convergence iteration.
+            if iteration >= max_build_iterations:
+                break
+            if _budget_exhausted(project.llm_client):
+                logger.warning("Convergence halted: LLM budget exhausted.")
+                report.key_decisions.append(
+                    "Convergence halted: budget exhausted before next iteration"
+                )
+                break
+            # No-progress guards: don't loop on an iteration that ran nothing or
+            # produced the identical failure signature.
+            if tasks_this_iter == 0:
+                break
+            if prev_issues is not None and prev_issues == issues:
+                report.key_decisions.append(
+                    f"Convergence halted: iteration {iteration} reproduced the "
+                    "identical gate failures (no progress)"
+                )
+                break
+            prev_issues = list(issues)
+
+            # Build a targeted fix spec from the concrete gate failures plus any
+            # failed/deferred tasks, re-decompose it, and re-run the same path.
+            fix_spec = self._build_fix_spec(report, issues, final_health)
+            fix_tasks = decompose_spec(
+                fix_spec,
+                assessment,
+                mode,
+                project.llm_client,
+                str(project.path),
+                max_tasks=max_tasks,
+                file_map=file_map,
+                targets=targets,
+            )
+            tasks = topological_sort(fix_tasks)
+            report.key_decisions.append(
+                f"Convergence iteration {iteration + 1}: re-attempting "
+                f"{len(issues)} gate failure(s) with {len(tasks)} fix task(s)"
+            )
+            if not tasks:
+                report.key_decisions.append(
+                    f"Convergence halted: iteration {iteration + 1} produced no "
+                    "fix tasks"
+                )
+                break
+
+        # Optional goal-completion check (off by default). Runs AFTER the gate
+        # loop has settled: an LLM judge reads the goal, acceptance criteria, and
+        # the cumulative diff and reports whether the goal is actually met (gates
+        # green != goal met). Advisory by default — gaps are recorded and logged
+        # but do not fail the build; it blocks only when block_on_goal_gap is set.
+        # Timeout-bounded and best-effort, so it can never hang or crash a build.
+        if get_setting(project.config, "orchestrator", "goal_check"):
+            self._run_goal_check(project, prompt, tasks, goal_check_base, report)
+
+        # Phase 6: Metacognitive Audit (best-effort; never fail a finished build)
+        report.finalize()
+        try:
+            auditor.audit_session(
+                report.completed_tasks, report.failed_tasks, str(report.scratchpad)
+            )
+        except Exception as e:
+            logger.warning(f"Session audit failed (non-fatal): {e}")
+            report.degraded_subsystems.append(f"Session audit: {e}")
+
+        usage = project.llm_client.cumulative_usage
+        report.llm_calls = usage.call_count
+        report.llm_tokens = usage.total_tokens
+        report.llm_prompt_tokens = getattr(usage, "prompt_tokens", 0)
+        report.llm_completion_tokens = getattr(usage, "completion_tokens", 0)
+        report.llm_cache_read_tokens = getattr(usage, "cache_read_tokens", 0)
+        report.llm_cost = usage.estimated_cost
+        report.cost_by_task = dict(getattr(project.llm_client, "cost_by_task", {}))
+
+        report.save(project.path)
+        return report.to_markdown()
+
+    def _capture_head(self, project: Project) -> Optional[str]:
+        """Best-effort current HEAD sha, or None outside a git repo / on error."""
+        if not (project.path / ".git").exists():
+            return None
+        proc = run_git("git rev-parse HEAD", project.path)
+        if proc is None:
+            return None
+        sha = proc.stdout.strip()
+        return sha if proc.returncode == 0 and sha else None
+
+    def _cumulative_diff(self, project: Project, base: Optional[str]) -> str:
+        """Diff of the whole build's work for the goal-check judge.
+
+        When a pre-build base sha is known, diff ``base`` against the working
+        tree (committed task commits + uncommitted changes). Otherwise fall back
+        to the working-tree diff vs HEAD. Best-effort: returns "" on any error or
+        outside a git repo, which the judge treats as no diff.
+        """
+        if not (project.path / ".git").exists():
+            return ""
+        cmd = f"git diff {base}" if base else "git diff HEAD"
+        proc = run_git(cmd, project.path)
+        return proc.stdout if proc and proc.returncode == 0 else ""
+
+    def _run_goal_check(
+        self,
+        project: Project,
+        prompt: str,
+        tasks: list,
+        base: Optional[str],
+        report: BuildReport,
+    ) -> None:
+        """Run the optional goal-completion check and record its verdict.
+
+        Advisory by default: a GAP verdict records gaps into the report and logs
+        them but does NOT fail the build. It blocks (marks validation failed and
+        appends a blocking issue) only when ``orchestrator.block_on_goal_gap`` is
+        true. SKIP (no goal/criteria/client, unparseable, timeout, error) is a
+        no-op. Wrapped so a judge failure can never crash a finished build.
+        """
+        from misterdev.core.verification.goal_check import (
+            GAP,
+            build_evidence,
+            run_goal_check,
+        )
+
+        try:
+            criteria = "\n".join(
+                f"- {t.acceptance_criteria}"
+                for t in tasks
+                if getattr(t, "acceptance_criteria", "")
+            )
+            diff = self._cumulative_diff(project, base)
+            summary = "; ".join(
+                t.title or t.description[:60] for t in report.completed_tasks
+            )
+            evidence = build_evidence(diff=diff, summary=summary)
+            timeout = get_setting(project.config, "orchestrator", "goal_check_timeout")
+            judge_model = (project.config.get("judge") or {}).get("model")
+            verdict = run_goal_check(
+                prompt,
+                criteria,
+                evidence,
+                llm_client=project.llm_client,
+                judge_model=judge_model,
+                timeout=timeout,
+            )
+        except Exception as e:
+            logger.warning(f"Goal-completion check failed (non-fatal): {e}")
+            report.degraded_subsystems.append(f"Goal-completion check: {e}")
+            return
+
+        if verdict.status != GAP:
+            logger.info(f"Goal-completion check: {verdict.status} ({verdict.reason})")
+            return
+
+        report.goal_gaps = list(verdict.gaps)
+        logger.warning(f"Goal-completion check found {len(verdict.gaps)} gap(s):")
+        for gap in verdict.gaps:
+            logger.warning(f"  goal gap: {gap}")
+
+        if get_setting(project.config, "orchestrator", "block_on_goal_gap"):
+            report.validation_passed = False
+            self.last_build_succeeded = False
+            issue = "Goal-completion check: " + "; ".join(verdict.gaps)
+            if report.validation is not None:
+                report.validation.issues.append(issue)
+            else:
+                report.key_decisions.append(issue)
+
+    def _build_fix_spec(
+        self,
+        report: BuildReport,
+        issues: list[str],
+        final_health: HealthCheck,
+    ) -> str:
+        """Compose a targeted spec from the gate's concrete failures.
+
+        Used by the convergence loop for iterations 2+: instead of re-running
+        expensive discovery, it points decomposition straight at what the gate
+        flagged (build/test/lint output, failed and deferred tasks) so the next
+        pass fixes the gap rather than re-planning the whole build.
+        """
+        parts = ["# Convergence Fix Spec", "## Goal: make the gate pass\n"]
+        if issues:
+            parts.append("### Gate Failures")
+            for item in issues:
+                parts.append(f"- {item}")
+        if not final_health.builds and final_health.build_output:
+            parts.append(f"\n### Build Output\n{final_health.build_output[:1000]}")
+        if not final_health.tests_pass and final_health.test_output:
+            parts.append(f"\n### Test Output\n{final_health.test_output[:1000]}")
+        if not final_health.lint_clean and final_health.lint_output:
+            parts.append(f"\n### Lint Output\n{final_health.lint_output[:1000]}")
+        if report.failed_tasks:
+            parts.append("\n### Failed Tasks")
+            for t in report.failed_tasks:
+                parts.append(f"- {t.id}: {t.title}")
+        if report.deferred_tasks:
+            parts.append("\n### Deferred Tasks")
+            for t in report.deferred_tasks:
+                parts.append(f"- {t.id}: {t.title}")
+        return "\n".join(parts)
+
+    @staticmethod
+    def _wave_commits(executor, project, tasks) -> list:
+        """Collect ``(task_id, sha)`` for each task that has a recorded commit,
+        skipping tasks with none. Shared by the regression-revert and
+        integration-gate paths."""
+        commits = []
+        for t in tasks:
+            sha = executor.find_task_commit(project, t.id)
+            if sha:
+                commits.append((t.id, sha))
+        return commits
+
+    def _maybe_rollback_regression(
+        self,
+        project: Project,
+        report: BuildReport,
+        assessment: ProjectAssessment,
+        flags: BuildFlags,
+    ) -> None:
+        """If the post-build gate failed, bisect task commits and revert the culprit."""
+        if flags.no_rollback or not report.completed_tasks:
+            return
+        test_cmd = assessment.structure.test_command
+        if not test_cmd:
+            return
+        ex = MarkdownPlanExecutor()
+        if not ex._is_git_repo(project):
+            return
+        commits = self._wave_commits(ex, project, report.completed_tasks)
+        if not commits:
+            return
+        logger.warning("Post-build regression detected; bisecting task commits...")
+        culprit = ex.bisect_regression(project, commits, test_cmd)
+        if not culprit:
+            logger.info("Bisect did not isolate a single task commit.")
+            return
+        sha = dict(commits)[culprit]
+        if ex.revert_task_commit(project, sha):
+            logger.warning(
+                f"Regression bisected to {culprit}; commit {sha[:8]} reverted."
+            )
+            report.key_decisions.append(
+                f"Regression from {culprit} auto-reverted (bisect)"
+            )
+
+    def _suite_failures(
+        self,
+        project: Project,
+        executor: MarkdownPlanExecutor,
+        test_cmd: str,
+        timeout: int,
+        cwd=None,
+    ) -> Optional[int]:
+        """Full-suite failure count: 0 when green, the parsed count when red, or
+        None when the count can't be parsed (caller then can't count-compare).
+
+        ``cwd`` runs the command in a sub-project (target) directory; defaults to
+        the repo root."""
+        from misterdev.core.verification.validator import (
+            _parse_test_counts,
+        )
+
+        ok, output = executor._run_command(project, test_cmd, timeout=timeout, cwd=cwd)
+        if ok:
+            return 0
+        total, failures = _parse_test_counts(output)
+        return failures if total > 0 else None
+
+    def _integration_gate_count(
+        self,
+        project: Project,
+        executor: MarkdownPlanExecutor,
+        test_cmd: str,
+        wave_tasks: list[Task],
+        timeout: int,
+        baseline_failures: int,
+    ) -> list[str]:
+        """Count-mode gate for a RED baseline: revert wave commits (newest first)
+        only when the wave RAISED the full-suite failure count above the baseline.
+
+        This closes the gap where, with the binary gate disabled by a red
+        baseline, a task gated on its own scoped tests could worsen the overall
+        suite and still commit. An unparseable post-wave count is left alone (we
+        do not revert on a number we can't read).
+        """
+        after = self._suite_failures(project, executor, test_cmd, timeout)
+        if after is None or after <= baseline_failures:
+            return []
+        logger.warning(
+            f"Integration gate (count): failures rose {baseline_failures} -> "
+            f"{after}; reverting wave commits until restored."
+        )
+        commits = self._wave_commits(executor, project, wave_tasks)
+        reverted: list[str] = []
+        for tid, sha in reversed(commits):
+            if executor.revert_task_commit(project, sha):
+                reverted.append(tid)
+            now = self._suite_failures(project, executor, test_cmd, timeout)
+            if now is not None and now <= baseline_failures:
+                break
+        return reverted
+
+    @staticmethod
+    def _target_regressed(after: Optional[int], baseline: Optional[int]) -> bool:
+        """Did a target's gate regress vs its baseline?
+
+        ``after``/``baseline`` are :meth:`_suite_failures` results (0 green, N
+        count, None unparseable). A green-now gate never regressed. With no
+        countable baseline we can't compare, so we don't revert. A binary failure
+        now (None) is a regression only if the target was green (baseline 0);
+        otherwise compare counts.
+        """
+        if after == 0:
+            return False
+        if baseline is None:
+            return False
+        if after is None:
+            return baseline == 0
+        return after > baseline
+
+    def _integration_gate_targets(
+        self,
+        project: Project,
+        executor: MarkdownPlanExecutor,
+        targets: list[dict],
+        wave_tasks: list[Task],
+        timeout: int,
+        target_baselines: dict,
+    ) -> list[str]:
+        """Per-target integration gate: validate each sub-project the wave touched
+        with ITS own toolchain (in ITS directory), reverting only the wave commits
+        belonging to a target that regressed. This is the multi-target analogue of
+        :meth:`_integration_gate` — the last place a polyglot run would otherwise
+        gate with the wrong toolchain.
+        """
+        from misterdev.core.planning.targets import select_target
+
+        reverted: list[str] = []
+        for tgt in targets:
+            gate_cmd = tgt.get("test_command") or tgt.get("build_command")
+            if not gate_cmd:
+                continue
+            tname = tgt.get("name") or tgt.get("path")
+            tp = (tgt.get("path") or "").strip("/")
+            run_dir = project.path / tp if tp else project.path
+            owned = [
+                t
+                for t in wave_tasks
+                if (
+                    select_target(
+                        targets, list(t.files_to_modify) + list(t.files_to_create)
+                    )
+                    or {}
+                ).get("path")
+                == tgt.get("path")
+            ]
+            if not owned:
+                continue
+            baseline = target_baselines.get(tname)
+            after = self._suite_failures(
+                project, executor, gate_cmd, timeout, cwd=run_dir
+            )
+            if not self._target_regressed(after, baseline):
+                continue
+            logger.warning(
+                f"Integration gate [{tname}]: regressed (baseline={baseline}, "
+                f"after={after}); reverting this target's wave commits."
+            )
+            commits = [(t.id, executor.find_task_commit(project, t.id)) for t in owned]
+            commits = [(tid, sha) for tid, sha in commits if sha]
+            for tid, sha in reversed(commits):
+                if executor.revert_task_commit(project, sha):
+                    reverted.append(tid)
+                now = self._suite_failures(
+                    project, executor, gate_cmd, timeout, cwd=run_dir
+                )
+                if not self._target_regressed(now, baseline):
+                    break
+        return reverted
+
+    def _integration_gate(
+        self,
+        project: Project,
+        executor: MarkdownPlanExecutor,
+        test_cmd: str,
+        wave_tasks: list[Task],
+        timeout: int,
+        baseline_failures: int = 0,
+    ) -> list[str]:
+        """Run the full suite after a wave; revert task commits that regressed it.
+
+        Returns the task_ids whose commits were reverted (empty if the suite
+        still passes). Bisects to the single culprit when possible; if that
+        can't isolate it or the tree is still red afterward, reverts the
+        remaining wave commits (newest first) to restore a green baseline. When
+        ``baseline_failures`` > 0 (a red baseline that could still be counted),
+        runs in count mode instead — reverting only a wave that raises the count.
+        """
+        if baseline_failures > 0:
+            return self._integration_gate_count(
+                project, executor, test_cmd, wave_tasks, timeout, baseline_failures
+            )
+        ok, _ = executor._run_command(project, test_cmd, timeout=timeout)
+        if ok:
+            return []
+
+        commits = self._wave_commits(executor, project, wave_tasks)
+        if not commits:
+            logger.warning(
+                "Integration gate: suite regressed but no task commits found to revert."
+            )
+            return []
+
+        logger.warning("Integration gate: suite regressed; isolating culprit...")
+        reverted: list[str] = []
+        culprit = executor.bisect_regression(
+            project, commits, test_cmd, timeout=timeout
+        )
+        if culprit:
+            sha = dict(commits)[culprit]
+            if executor.revert_task_commit(project, sha):
+                reverted.append(culprit)
+                ok, _ = executor._run_command(project, test_cmd, timeout=timeout)
+                if ok:
+                    return reverted
+
+        for tid, sha in reversed(commits):
+            if tid in reverted:
+                continue
+            if executor.revert_task_commit(project, sha):
+                reverted.append(tid)
+            ok, _ = executor._run_command(project, test_cmd, timeout=timeout)
+            if ok:
+                break
+        return reverted
+
+    def _execute_tasks(
+        self,
+        tasks: list[Task],
+        project: Project,
+        flags: BuildFlags,
+        report: BuildReport,
+    ) -> None:
+        scratchpad = Scratchpad()
+        aligner = RealTimeAligner(project.path)
+        contracts = ContractRegistry(project.path)
+        progress = ProgressTracker(project.path)
+        changes = ChangeTracker(project.path)
+        strategy_optimizer = StrategyOptimizer()
+        executor = MarkdownPlanExecutor(scratchpad=scratchpad)
+        report.scratchpad = scratchpad
+
+        max_consecutive_failures = get_setting(
+            project.config, "orchestrator", "max_consecutive_failures"
+        )
+
+        completed_ids = set(progress.completed)
+        failed_ids: set[str] = set()
+        consecutive_failures = 0
+        aborted = False
+        max_cost_per_task = get_setting(
+            project.config, "orchestrator", "max_cost_per_task"
+        )
+
+        # Register decomposed tasks with the TaskManager so status updates,
+        # progress tracking, and contract lookups resolve by ID (otherwise
+        # build()'s LLM-decomposed task IDs are unknown to the manager).
+        for task in tasks:
+            project.task_manager.tasks.setdefault(task.id, task)
+
+        if completed_ids:
+            logger.info(f"Resuming build: {len(completed_ids)} tasks already completed")
+
+        lang = (project.config.get("language") or "python").lower()
+        remaining = list(tasks)
+
+        # Integration gate: after each wave, re-run the full suite and revert
+        # any task whose merge regressed it. Per-task validation passes a task
+        # in isolation but can't see cross-module breakage that only surfaces
+        # when the whole package is imported together; without this, broken
+        # tasks accumulate under later merges until the end-of-build gate.
+        # Fold the golden suite into the per-wave gate so a task that breaks the
+        # immutable contract is bisected and reverted immediately, not just at
+        # the end-of-iteration GateKeeper.
+        test_cmd = _combine_commands(
+            report.assessment.structure.test_command,
+            get_setting(project.config, "orchestrator", "golden_command"),
+        )
+        test_timeout = get_setting(project.config, "build", "test_timeout")
+        gate_targets = project.config.get("targets") or []
+        gate_active = (
+            not flags.no_rollback
+            and get_setting(project.config, "orchestrator", "integration_gate")
+            and (bool(test_cmd) or bool(gate_targets))
+            and (Path(project.path) / ".git").exists()
+        )
+        # Per-target baselines (multi-target): measure each sub-project's gate in
+        # its own dir ONCE up front, so the per-wave gate reverts only a target
+        # that REGRESSED, and the executor's per-task gate uses the right baseline.
+        target_baselines: dict = {}
+        if gate_active and gate_targets:
+            for tgt in gate_targets:
+                gcmd = tgt.get("test_command") or tgt.get("build_command")
+                if not gcmd:
+                    continue
+                tname = tgt.get("name") or tgt.get("path")
+                tp = (tgt.get("path") or "").strip("/")
+                rdir = project.path / tp if tp else project.path
+                target_baselines[tname] = self._suite_failures(
+                    project, executor, gcmd, test_timeout, cwd=rdir
+                )
+            project.target_baselines = {
+                k: int(v or 0) for k, v in target_baselines.items()
+            }
+        baseline_failures = 0
+        if gate_active and test_cmd:
+            baseline_ok, baseline_out = executor._run_command(
+                project, test_cmd, timeout=test_timeout
+            )
+            if not baseline_ok:
+                # A red baseline used to fully disable the gate, so a task could
+                # WORSEN the suite (more failures than at the start) and still
+                # commit. Instead, run the gate in COUNT mode against the baseline
+                # failure count when it is parseable — reverting only a wave that
+                # increases failures. Unparseable count -> disable as before.
+                from misterdev.core.verification.validator import (
+                    _parse_test_counts,
+                )
+
+                total, fails = _parse_test_counts(baseline_out)
+                if total > 0 and fails > 0:
+                    baseline_failures = fails
+                    logger.info(
+                        f"Integration gate in COUNT mode: baseline has {fails} "
+                        "failing test(s); a wave that raises the count is reverted."
+                    )
+                else:
+                    logger.info(
+                        "Integration gate disabled: baseline failing and test "
+                        "count unparseable."
+                    )
+                    gate_active = False
+
+        while remaining and not aborted:
+            # Graceful budget stop: if the global budget is exhausted, do not
+            # launch another wave. Defer the remainder and break so the pipeline
+            # finalizes/reports normally instead of throwing mid-wave.
+            if _budget_exhausted(project.llm_client):
+                logger.warning("Stopping run: LLM budget exhausted.")
+                report.key_decisions.append(
+                    "Stopped: budget exhausted; remaining work deferred"
+                )
+                for task in remaining:
+                    report.deferred_tasks.append(task)
+                break
+
+            # Find all tasks whose dependencies are satisfied
+            ready = []
+            still_waiting = []
+            for task in remaining:
+                # Skip only if this exact task (id AND content hash) already
+                # completed. Hash-aware so a freshly decomposed plan that reuses
+                # generic ids (T-001...) from a prior build is not wrongly
+                # skipped against stale progress state.
+                if not progress.needs_rerun(
+                    task.id, compute_task_hash(task, project.path)
+                ):
+                    report.completed_tasks.append(task)
+                    completed_ids.add(task.id)
+                    continue
+                if any(d in failed_ids for d in task.dependencies):
+                    report.deferred_tasks.append(task)
+                    failed_ids.add(task.id)
+                    continue
+                if any(d not in completed_ids for d in task.dependencies):
+                    still_waiting.append(task)
+                    continue
+                ready.append(task)
+
+            if not ready:
+                for task in still_waiting:
+                    report.deferred_tasks.append(task)
+                break
+
+            # Prepare tasks with context
+            for task in ready:
+                strategy = strategy_optimizer.select_best_strategy(
+                    task.description,
+                    task.category,
+                    report.assessment.summary(),
+                    project.llm_client,
+                )
+                task.processor_data["strategy"] = strategy
+                task.processor_data["consensus_context"] = (
+                    aligner.get_consensus_context()
+                )
+                task.processor_data["interface_contracts"] = (
+                    contracts.get_contracts_for_task(task.dependencies)
+                )
+                task.processor_data["recent_changes"] = (
+                    changes.get_recent_changes_for_files(
+                        task.files_to_modify + task.files_to_create
+                    )
+                )
+
+            if flags.interactive:
+                filtered_ready = []
+                for task in ready:
+                    action = self._interactive_prompt(
+                        task, task.processor_data.get("strategy", "iterative")
+                    )
+                    if action == "quit":
+                        aborted = True
+                        break
+                    elif action == "skip":
+                        report.deferred_tasks.append(task)
+                    else:
+                        filtered_ready.append(task)
+                ready = filtered_ready
+                if aborted:
+                    break
+
+            if not ready:
+                remaining = still_waiting
+                continue
+
+            # Execute: parallel or sequential
+            wave_completed: list[Task] = []
+            if flags.parallel and len(ready) > 1:
+                logger.info(
+                    f"Executing {len(ready)} tasks in parallel: {[t.id for t in ready]}"
+                )
+                results = self._execute_parallel(ready, executor, project)
+            else:
+                results = []
+                for task in ready:
+                    try:
+                        result = executor.execute(task, project)
+                        results.append((task, result, None))
+                    except Exception as e:
+                        results.append((task, None, e))
+
+            # Process results
+            for task, result, error in results:
+                if isinstance(error, BudgetExceededError):
+                    # Budget ran out mid-task: revert any partial work and stop
+                    # the run gracefully rather than recording a failure.
+                    logger.warning(
+                        f"Stopping run: budget exhausted during {task.id} ({error})."
+                    )
+                    sha = executor.find_task_commit(project, task.id)
+                    if sha:
+                        executor.revert_task_commit(project, sha)
+                    report.deferred_tasks.append(task)
+                    report.key_decisions.append(
+                        "Stopped: budget exhausted; remaining work deferred"
+                    )
+                    aborted = True
+                    break
+                exceeded_fn = getattr(project.llm_client, "task_cost_exceeded", None)
+                if (
+                    max_cost_per_task is not None
+                    and exceeded_fn
+                    and exceeded_fn(task.id)
+                ):
+                    # This task alone blew its per-task cost cap: abandon and
+                    # revert it cleanly instead of burning more budget retrying.
+                    cap_fn = getattr(project.llm_client, "effective_task_cap", None)
+                    cap = (cap_fn(task.id) if cap_fn else None) or 0.0
+                    logger.warning(
+                        f"Task {task.id} hit per-task cost cap "
+                        f"(${cap:.2f}); abandoning and reverting."
+                    )
+                    sha = executor.find_task_commit(project, task.id)
+                    if sha:
+                        executor.revert_task_commit(project, sha)
+                    failed_ids.add(task.id)
+                    progress.mark_failed(task.id)
+                    report.deferred_tasks.append(task)
+                    report.key_decisions.append(
+                        f"Task {task.id} deferred: exceeded per-task cost cap "
+                        f"(${cap:.2f})"
+                    )
+                    continue
+                if error:
+                    logger.error(f"Task {task.id} raised: {error}")
+                    failed_ids.add(task.id)
+                    progress.mark_failed(task.id)
+                    report.failed_tasks.append(task)
+                    consecutive_failures += 1
+                elif result.status == "completed":
+                    task.execution_history.append(result)
+                    completed_ids.add(task.id)
+                    progress.mark_completed(
+                        task.id, compute_task_hash(task, project.path)
+                    )
+                    report.completed_tasks.append(task)
+                    wave_completed.append(task)
+                    consecutive_failures = 0
+                    modified = task.files_to_modify + task.files_to_create
+                    if modified:
+                        contracts.extract_contracts(
+                            task.id,
+                            modified,
+                            project.path,
+                            project.llm_client,
+                            language=lang,
+                        )
+                        changes.record_task_changes(task.id, modified)
+                    if task.complexity == "architectural":
+                        aligner.certify_decision(task.title, task.description)
+                else:
+                    task.execution_history.append(result)
+                    failed_ids.add(task.id)
+                    progress.mark_failed(task.id)
+                    report.failed_tasks.append(task)
+                    consecutive_failures += 1
+
+                if consecutive_failures >= max_consecutive_failures:
+                    aborted = True
+                    break
+
+            # Integration gate: after this wave's merges, revert any task that
+            # regressed the full suite before the next wave builds on top of it.
+            if gate_active and wave_completed:
+                if gate_targets:
+                    # Polyglot: gate each touched sub-project with its own
+                    # toolchain in its own directory (replaces the top-level gate,
+                    # which would use the wrong commands for a frontend wave).
+                    reverted = self._integration_gate_targets(
+                        project,
+                        executor,
+                        gate_targets,
+                        wave_completed,
+                        test_timeout,
+                        target_baselines,
+                    )
+                else:
+                    reverted = self._integration_gate(
+                        project,
+                        executor,
+                        test_cmd,
+                        wave_completed,
+                        test_timeout,
+                        baseline_failures=baseline_failures,
+                    )
+                for tid in reverted:
+                    completed_ids.discard(tid)
+                    failed_ids.add(tid)
+                    progress.mark_failed(tid)
+                    obj = next((t for t in wave_completed if t.id == tid), None)
+                    if obj is not None and obj in report.completed_tasks:
+                        report.completed_tasks.remove(obj)
+                        report.failed_tasks.append(obj)
+                    report.key_decisions.append(
+                        f"Integration gate: {tid} reverted (regressed full suite)"
+                    )
+                    consecutive_failures += 1
+                if reverted and consecutive_failures >= max_consecutive_failures:
+                    aborted = True
+
+            remaining = still_waiting
+
+        # Defer any unprocessed tasks
+        processed_ids = (
+            completed_ids | failed_ids | {t.id for t in report.deferred_tasks}
+        )
+        for task in tasks:
+            if task.id not in processed_ids:
+                report.deferred_tasks.append(task)
+
+    @staticmethod
+    def _task_file_set(task: Task) -> set:
+        """Declared files a task will touch (modify + create).
+
+        Tolerates non-list values (e.g. unconfigured mocks): only real lists
+        contribute paths, anything else is treated as "unknown / no claim".
+        """
+        files: set = set()
+        for attr in ("files_to_modify", "files_to_create"):
+            value = getattr(task, attr, None)
+            if isinstance(value, list):
+                files.update(str(p) for p in value)
+        return files
+
+    @classmethod
+    def _partition_disjoint(cls, ready: list[Task]) -> tuple[list, list]:
+        """Split tasks into a concurrent-safe group + a serial remainder.
+
+        A task joins the concurrent group only if its declared file set is
+        disjoint from every task already in that group; otherwise it is
+        deferred to the serial remainder so overlapping writes can't interleave.
+        """
+        concurrent_group: list = []
+        serial_remainder: list = []
+        claimed: set = set()
+        for task in ready:
+            files = cls._task_file_set(task)
+            if files & claimed:
+                serial_remainder.append(task)
+            else:
+                concurrent_group.append(task)
+                claimed |= files
+        return concurrent_group, serial_remainder
+
+    def _execute_parallel(
+        self, ready: list[Task], executor: MarkdownPlanExecutor, project: Project
+    ) -> list:
+        """Execute a batch of independent tasks concurrently.
+
+        In "worktree" mode each task runs in its own git worktree so parallel
+        edits can't collide. When the mode is left at its default and the
+        project is a git repo, worktree isolation is preferred automatically;
+        "shared" must be requested explicitly to opt out. In shared mode only
+        tasks with disjoint declared file sets run in the same concurrent batch;
+        tasks whose file sets overlap are run serially afterwards.
+        """
+        mode = get_setting(project.config, "orchestrator", "parallel_mode")
+        is_git_repo = (project.path / ".git").exists() is True
+        # "auto" (default) isolates via worktrees on a git repo; the value itself
+        # carries the intent, so no fragile "was it explicitly set" detection.
+        prefer_worktrees = mode == "worktree" or (mode == "auto" and is_git_repo)
+        if prefer_worktrees and is_git_repo:
+            return self._execute_parallel_worktrees(ready, executor, project)
+
+        concurrent_group, serial_remainder = self._partition_disjoint(ready)
+        results = []
+        max_workers = get_setting(project.config, "orchestrator", "max_workers")
+        if concurrent_group:
+            with concurrent.futures.ThreadPoolExecutor(
+                max_workers=min(len(concurrent_group), max_workers)
+            ) as pool:
+                future_to_task = {
+                    pool.submit(
+                        executor.execute, task, project, use_git_branch=False
+                    ): task
+                    for task in concurrent_group
+                }
+                for future in concurrent.futures.as_completed(future_to_task):
+                    task = future_to_task[future]
+                    try:
+                        result = future.result()
+                        results.append((task, result, None))
+                    except Exception as e:
+                        results.append((task, None, e))
+
+        # Tasks with overlapping file claims run one at a time.
+        for task in serial_remainder:
+            try:
+                result = executor.execute(task, project, use_git_branch=False)
+                results.append((task, result, None))
+            except Exception as e:
+                results.append((task, None, e))
+        return results
+
+    def _execute_parallel_worktrees(
+        self, ready: list[Task], executor: MarkdownPlanExecutor, project: Project
+    ) -> list:
+        """Run each task in an isolated git worktree, then merge successes back.
+
+        Worktrees are created and merged serially (git's index/worktree metadata
+        is not concurrency-safe); only the task bodies run in parallel.
+        """
+        import uuid
+        from misterdev.tools.git_tool import GitTool
+
+        git = GitTool({})
+        wt_root = project.path / ".orchestrator" / "worktrees"
+        wt_root.mkdir(parents=True, exist_ok=True)
+        results: list = []
+        prepared: list = []
+
+        for task in ready:
+            branch = f"task/{task.id}"
+            wt_path = wt_root / f"{task.id}-{uuid.uuid4().hex[:6]}"
+            ok, out = git.worktree_add(project, str(wt_path), branch, new_branch=True)
+            if ok:
+                prepared.append((task, wt_path, branch))
+            else:
+                logger.error(f"Worktree add failed for {task.id}: {out}")
+                results.append(
+                    (task, None, RuntimeError(f"worktree add failed: {out}"))
+                )
+
+        def run_one(item):
+            task, wt_path, branch = item
+            view = _WorktreeProjectView(project, wt_path)
+            try:
+                return (
+                    task,
+                    executor.execute(task, view, use_git_branch=False),
+                    None,
+                    wt_path,
+                    branch,
+                )
+            except Exception as e:
+                return (task, None, e, wt_path, branch)
+
+        max_workers = get_setting(project.config, "orchestrator", "max_workers")
+        raw = []
+        if prepared:
+            with concurrent.futures.ThreadPoolExecutor(
+                max_workers=min(len(prepared), max_workers)
+            ) as pool:
+                futures = [pool.submit(run_one, item) for item in prepared]
+                raw = [f.result() for f in concurrent.futures.as_completed(futures)]
+
+        for task, result, error, wt_path, branch in raw:
+            if result is not None and getattr(result, "status", None) == "completed":
+                merged, mout = git.merge_worktree(project, branch)
+                if not merged:
+                    logger.error(f"Worktree merge failed for {task.id}: {mout}")
+                    error, result = RuntimeError(f"merge failed: {mout}"), None
+            git.worktree_remove(project, str(wt_path))
+            results.append((task, result, error))
+        return results
+
+    def _interactive_prompt(self, task: Task, strategy: str = "iterative") -> str:
+        console.print(
+            f"\n[bold cyan]Next Task:[/] [{task.id}] {task.title} ([bold magenta]{strategy.upper()}[/])"
+        )
+        choice = Prompt.ask("Proceed?", choices=["y", "n", "s", "q"], default="y")
+        return {"y": "proceed", "q": "quit", "s": "skip", "n": "quit"}[choice]
+
+    def _generate_spec(
+        self,
+        mode: BuildMode,
+        prompt: str,
+        assessment: ProjectAssessment,
+        project: Project,
+        facts: str = "",
+    ) -> str:
+        """Phase 2: Generate a spec based on mode."""
+        if mode == BuildMode.DEBUG:
+            parts = ["# Debug Spec\n## Broken Items"]
+            for item in assessment.features.broken:
+                parts.append(f"- {item}")
+            if assessment.features.stubs:
+                parts.append("\n## Stubs")
+                for item in assessment.features.stubs:
+                    parts.append(f"- {item}")
+            if not assessment.health.builds:
+                parts.append(
+                    f"\n## Build Failure\n{assessment.health.build_output[:500]}"
+                )
+            if not assessment.health.tests_pass:
+                parts.append(
+                    f"\n## Test Failures\n{assessment.health.test_output[:500]}"
+                )
+            return "\n".join(parts)
+
+        if mode == BuildMode.COMPLETE:
+            parts = [
+                f"# Completion Spec\n## Project: {project.name}",
+                "## Goal: Complete all work\n",
+                "### Must Complete",
+            ]
+            for f in assessment.features.incomplete:
+                parts.append(f"- {f.name}: {f.description}")
+            parts.append("\n### Must Fix")
+            for item in assessment.features.broken:
+                parts.append(f"- {item}")
+            for item in assessment.features.stubs:
+                parts.append(f"- Stub: {item}")
+            parts.append("\n### Should Add")
+            for f in assessment.features.missing:
+                parts.append(f"- {f.name}: {f.description}")
+            if assessment.features.todos:
+                parts.append(f"\n### TODOs ({len(assessment.features.todos)} items)")
+                for todo in assessment.features.todos[:20]:
+                    parts.append(
+                        f"- {todo.get('file', '?')}:{todo.get('line', '?')} {todo.get('text', '')}"
+                    )
+            return "\n".join(parts)
+
+        if mode == BuildMode.SPEC:
+            spec_path = project.path / prompt.strip()
+            if spec_path.exists():
+                return spec_path.read_text(encoding="utf-8")
+            return f"Spec file not found: {prompt}"
+
+        if mode in (BuildMode.CREATE, BuildMode.SMART):
+            expand_prompt = (
+                f"Expand the following into a comprehensive project spec.\n"
+                f"Include: features with acceptance criteria, error handling, "
+                f"input validation, testing strategy, architecture decisions.\n\n"
+                f"Project context: {assessment.context.purpose}\n"
+                f"Conventions: {assessment.context.conventions}\n"
+                f"Languages: {assessment.structure.languages}\n"
+                f"Frameworks: {assessment.structure.frameworks}\n"
+                f"Existing features: {[f.name for f in assessment.features.existing]}\n"
+                f"Verified facts: {facts}\n\n"
+                f"Description: {prompt}\n\nReturn the spec as markdown."
+            )
+            return project.llm_client.generate_code(
+                expand_prompt,
+                "You are a software architect writing a project specification.",
+            )
+
+        if mode == BuildMode.REVIEW:
+            return (
+                f"# Review Spec\nReview and fix all issues found in the project.\n"
+                f"Broken: {assessment.features.broken}\n"
+                f"Stubs: {assessment.features.stubs}\n"
+                f"TODOs: {len(assessment.features.todos)} items"
+            )
+
+        return f"# Auto Spec\n{prompt}"
+
+    def _setup_env(self, project: Project) -> Optional[str]:
+        """Initialize the project's env manager and return its activation prefix."""
+        if project.env_manager:
+            project.env_manager.setup()
+            return project.env_manager.activate_command()
+        return None
+
+    def _container_engine(self, project: Project):
+        """Return the project's container engine if a container environment is
+        configured and an engine is available, else None (gates run locally).
+
+        ``_setup_env`` has already called ``setup()``, so the engine is
+        detected by the time gates run.
+        """
+        from misterdev.environments.container_env import (
+            ContainerEnvironmentManager,
+        )
+
+        env = project.env_manager
+        if isinstance(env, ContainerEnvironmentManager):
+            return env.engine()
+        return None
+
+    def _project_file_map(self, project: Project) -> str:
+        """The project's real file+symbol outline, for grounding decomposition.
+
+        Best-effort: builds the symbol graph (idempotent) and returns its project
+        outline, or "" if topography is unavailable or errors — the decomposer
+        then falls back to cautious path inference rather than failing.
+        """
+        topo = getattr(project, "topography", None)
+        if topo is None:
+            return ""
+        try:
+            topo.initialize()
+            return topo.get_project_outline()
+        except Exception as e:
+            logger.warning(f"File map unavailable for decomposition (non-fatal): {e}")
+            return ""
+
+    @staticmethod
+    def _resolve_claim_file(root: Path, label: str, file_map: str) -> Optional[Path]:
+        """Best-effort map a claim label to a real file for evidence.
+
+        A label that is itself a path wins. Otherwise its DISTINCTIVE identifier
+        tokens (length >= 5, or CamelCase) are matched as WHOLE WORDS against the
+        file+symbol map, longest first, and the first file that mentions one is
+        used. The word-boundary + distinctiveness rules stop a generic token like
+        "backend" from matching an unrelated ``backend_registry.py``. Returns None
+        when nothing resolves — the caller then leaves the claim unverified rather
+        than judging it against the wrong file.
+        """
+        if label:
+            direct = root / label
+            if direct.is_file():
+                return direct
+        tokens = sorted(
+            {
+                t
+                for t in re.findall(r"[A-Za-z_][A-Za-z0-9_]{3,}", label or "")
+                if len(t) >= 5 or any(c.isupper() for c in t)
+            },
+            key=len,
+            reverse=True,
+        )
+        for token in tokens:
+            pattern = re.compile(rf"\b{re.escape(token)}\b")
+            for line in file_map.splitlines():
+                if pattern.search(line):
+                    cand = root / line.split(":", 1)[0].strip()
+                    if cand.is_file():
+                        return cand
+        return None
+
+    def _verify_completeness_claims(
+        self, project: Project, assessment: ProjectAssessment, report: BuildReport
+    ) -> None:
+        """Drop completeness claims a second component refutes against the source.
+
+        The analyzer flags "incomplete"/"stub" items from a lossy overview, so it
+        can mislabel deliberate design (graceful-degradation, platform no-ops,
+        parity shims) as work. Before the spec and tasks are built, recheck each
+        claim against the REAL file plus the verified build/test state with an
+        independent verifier and prune only the ones it refutes WITH evidence;
+        unsure / skip / timeout keeps the claim, so genuine work is never lost.
+        No-op when disabled or when no LLM verifier is available.
+        """
+        if not get_setting(project.config, "orchestrator", "verify_claims"):
+            return
+        feats = assessment.features
+        if not feats.incomplete and not feats.stubs:
+            logger.info(
+                "Completeness-claim verifier: no incomplete/stub claims flagged; "
+                "nothing to verify."
+            )
+            return
+
+        from misterdev.analyzers.project_analyzer import (
+            _health_ground_truth,
+        )
+        from misterdev.core.verification.claim_verifier import (
+            Claim,
+            verify_claims,
+        )
+
+        root = project.path
+        health = _health_ground_truth(assessment.health)
+        file_map = self._project_file_map(project)
+
+        def read_body(path: Optional[Path]) -> str:
+            if path is None or not path.is_file():
+                return ""
+            try:
+                return path.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                return ""
+
+        # Build a claim ONLY when the claimed file's real source is in hand. Without
+        # it the verifier would see just the "build passes" line — which the prompt
+        # treats as grounds to refute — and could drop a genuine claim on no
+        # evidence, so an unresolved claim is KEPT, unverified. `health` goes FIRST
+        # so it survives the verifier's evidence truncation. `origin` is the
+        # assessment object/string, so pruning is by identity and a shared or empty
+        # label can't drop the wrong claim.
+        entries = []  # (Claim, kind, origin)
+        unverified = 0
+        for fi in feats.incomplete:
+            path = self._resolve_claim_file(root, fi.name, file_map)
+            body = read_body(path)
+            if not body:
+                unverified += 1
+                continue
+            try:
+                rel = path.relative_to(root)
+            except ValueError:
+                rel = path
+            entries.append(
+                (
+                    Claim(
+                        kind="incomplete",
+                        label=fi.name,
+                        description=f"{fi.description} (source file: {rel})",
+                        evidence=f"{health}\n\n{body}",
+                    ),
+                    "incomplete",
+                    fi,
+                )
+            )
+        for sp in feats.stubs:
+            if not isinstance(sp, str):
+                continue
+            body = read_body(root / sp)
+            if not body:
+                unverified += 1
+                continue
+            entries.append(
+                (
+                    Claim(
+                        kind="stub",
+                        label=sp,
+                        description=f"flagged as a stub file (source file: {sp})",
+                        evidence=f"{health}\n\n{body}",
+                    ),
+                    "stub",
+                    sp,
+                )
+            )
+
+        if not entries:
+            logger.info(
+                "Completeness-claim verifier: no claims with readable source to "
+                f"verify ({unverified} kept unverified)."
+            )
+            return
+
+        judge_model = (project.config.get("judge") or {}).get("model")
+        timeout = get_setting(project.config, "orchestrator", "verify_claims_timeout")
+        logger.info(
+            f"Verifying {len(entries)} completeness claim(s) against the real source..."
+        )
+        try:
+            verdicts = verify_claims(
+                [claim for claim, _, _ in entries],
+                llm_client=project.llm_client,
+                model=judge_model,
+                timeout=timeout,
+            )
+        except Exception as e:  # the gate must never crash a build
+            logger.warning(f"Completeness-claim verification failed (non-fatal): {e}")
+            report.degraded_subsystems.append(f"Claim verifier: {e}")
+            return
+
+        drop_incomplete: set[int] = set()
+        drop_stubs: set[str] = set()
+        for (claim, kind, origin), v in zip(entries, verdicts):
+            if not v.refuted:
+                continue
+            if kind == "incomplete":
+                drop_incomplete.add(id(origin))
+            else:
+                drop_stubs.add(origin)
+            msg = f"Dropped phantom completeness claim '{claim.label}': {v.reason}"
+            logger.info(msg)
+            report.key_decisions.append(msg)
+
+        dropped = len(drop_incomplete) + len(drop_stubs)
+        logger.info(
+            f"Completeness-claim verification: {len(entries) - dropped} kept, "
+            f"{dropped} dropped ({unverified} unverified)."
+        )
+        if dropped:
+            feats.incomplete = [
+                fi for fi in feats.incomplete if id(fi) not in drop_incomplete
+            ]
+            feats.stubs = [sp for sp in feats.stubs if sp not in drop_stubs]
+
+    def _resolve_targets(self, project: Project) -> list[dict]:
+        """Explicit ``targets`` if declared, else auto-discovered when enabled.
+
+        Discovered targets are written back into ``project.config['targets']`` so
+        the executor's per-task routing and per-target validation see them too.
+        """
+        explicit = project.config.get("targets") or []
+        if explicit:
+            return explicit
+        if not get_setting(project.config, "orchestrator", "auto_targets"):
+            return []
+        from misterdev.core.planning.targets import discover_targets
+
+        discovered = discover_targets(str(project.path))
+        if discovered:
+            names = ", ".join(t["name"] for t in discovered)
+            logger.info(
+                f"Auto-discovered {len(discovered)} polyglot target(s): {names}"
+            )
+            project.config["targets"] = discovered
+        return discovered
+
+    def _validate_targets(
+        self, project: Project, env_activate: Optional[str]
+    ) -> list[dict]:
+        """Validate each declared target with its OWN toolchain, vs its baseline.
+
+        Closes the multi-target gap where the end-of-run GateKeeper only ran the
+        top-level commands. Crucially this compares against each target's baseline
+        (measured before the run, stored on ``project.target_baselines``), so a
+        target that was ALREADY broken (e.g. a frontend with pre-existing errors)
+        is not counted as a failure for a run that never touched it — only a
+        genuine REGRESSION fails. Returns [] when no targets are declared, so
+        single-target builds are unaffected.
+        """
+        targets = project.config.get("targets") or []
+        if not targets:
+            return []
+        # getattr seam lets tests inject a fake runner; prod creates a real one.
+        executor = getattr(self, "_validate_executor", None) or MarkdownPlanExecutor()
+        target_baselines = getattr(project, "target_baselines", {}) or {}
+        build_to = get_setting(project.config, "build", "build_timeout")
+        test_to = get_setting(project.config, "build", "test_timeout")
+        results: list[dict] = []
+        for t in targets:
+            gate_cmd = t.get("test_command") or t.get("build_command")
+            if not gate_cmd:
+                continue
+            name = t.get("name") or t.get("path") or "?"
+            tp = (t.get("path") or "").strip("/")
+            run_dir = project.path / tp if tp else project.path
+            timeout = test_to if t.get("test_command") else build_to
+            after = self._suite_failures(
+                project, executor, gate_cmd, timeout, cwd=run_dir
+            )
+            baseline = target_baselines.get(name)
+            regressed = self._target_regressed(after, baseline)
+            ok = not regressed
+            detail = "ok" if ok else f"regressed (baseline={baseline}, after={after})"
+            # Behavioral verification (opt-in): a frontend target may declare a
+            # `web`/`vision` block to verify it actually RENDERS/works, not just
+            # type-checks. Only run when the build/test gate is already clean.
+            if ok and (t.get("web") or t.get("vision")):
+                ok, rt_detail = self._run_target_runtime_gates(project, t, run_dir)
+                if not ok:
+                    detail = rt_detail
+            results.append({"name": name, "ok": ok, "detail": detail})
+        return results
+
+    def _run_target_runtime_gates(
+        self, project: Project, target: dict, run_dir
+    ) -> tuple[bool, str]:
+        """Run a target's opt-in web/vision behavioral gates in its directory.
+
+        Mirrors the GateKeeper's G4.7/G4.8 but scoped to a sub-project: the web
+        gate renders + screenshots, the vision gate judges that screenshot. Both
+        are best-effort and timeout-bounded — only a RED (a real failed check)
+        fails the target; a SKIP (no browser/model/config) passes.
+        """
+        evidence = None
+        web_cfg = target.get("web")
+        if web_cfg:
+            from misterdev.core.verification.web_verify import (
+                run_web_gate,
+            )
+
+            web = run_web_gate(run_dir, web_cfg)
+            evidence = getattr(web, "evidence", None)
+            if web.status == "red":
+                return False, f"web verify failed ({web.reason or 'no detail'})"
+        vision_cfg = target.get("vision")
+        if vision_cfg:
+            from misterdev.core.verification.vision_verify import (
+                run_vision_gate,
+            )
+
+            vc = dict(vision_cfg)
+            if not vc.get("capture") and evidence:
+                vc["capture"] = evidence
+            vision = run_vision_gate(
+                run_dir, vc or None, llm_client=getattr(project, "llm_client", None)
+            )
+            if vision.status == "red":
+                return False, f"vision verify failed ({vision.reason or 'no detail'})"
+        return True, "ok"
+
+    def _analyze(self, project: Project, env_activate: Optional[str]):
+        """Phase 1 analysis with config-driven commands and timeouts.
+
+        Shared by build() and interactive_plan() so the analyzer's parameters
+        (and any future config wiring) live in exactly one place.
+        """
+        # Build the project's symbol graph ONCE via its TopographyEngine and feed
+        # the outline to the analyzer, instead of letting the source overview parse
+        # a second throwaway graph. The engine's initialize() is idempotent, so the
+        # later decomposition/file-map calls reuse this same graph.
+        project_outline = self._project_file_map(project) or None
+        return analyze_project(
+            project.path,
+            project.llm_client,
+            build_command=project.config.get("build_command"),
+            test_command=project.config.get("test_command"),
+            lint_command=project.config.get("lint_command"),
+            env_activate=env_activate,
+            build_timeout=get_setting(project.config, "build", "build_timeout"),
+            test_timeout=get_setting(project.config, "build", "test_timeout"),
+            lint_timeout=get_setting(project.config, "build", "lint_timeout"),
+            parallel=get_setting(project.config, "build", "parallel_analysis"),
+            project_outline=project_outline,
+        )
+
+    def _get_or_register(self, project_path: str | Path) -> Optional[Project]:
+        project = self.registry.get_project(project_path)
+        if not project:
+            try:
+                project = self.registry.register_project(project_path)
+            except Exception as e:
+                logger.error(f"Failed to register project at {project_path}: {e}")
+                return None
+        return project