alysis-code 0.13.0__py3-none-any.whl

alysis_code/replanning.py

@@ -0,0 +1,1195 @@
+from __future__ import annotations
+
+import copy
+import json
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from .assets.models import AssetError
+from .assets.replanner_context import (
+    ReplannerAssetsBundle,
+    build_replanner_assets_bundle,
+    replanner_bundle_as_planner_bundle,
+)
+from .assets.surface import build_asset_surface
+from .atomic_io import atomic_write_json, atomic_write_text
+from .config import AppConfig
+from .direction_change import filter_obsolete_direction_paths
+from .forge import RunPaths, now_iso, save_plan
+from .integration_gate import IntegrationGateResult
+from .knowledge_base import (
+    KnowledgeIndexEntry,
+    is_effectively_accepted_task_attempt,
+    is_effectively_open_status,
+    load_knowledge_index,
+)
+from .knowledge_librarian import (
+    MaterializedKnowledgeSelection,
+    prepare_relevant_knowledge,
+    select_relevant_knowledge,
+)
+from .model_registry import ModelRegistry
+from .model_router import ROLE_PLANNER, resolve_model_for_role
+from .plan_assistant import (
+    PlanApplyResult,
+    PlannerTurnResult,
+    apply_guarded_planner_plan_update,
+    protected_task_ids,
+    run_planner_turn,
+    summarize_plan_update,
+)
+from .plan_repair import PlannerRepairReport, apply_plan_status, record_plan_repair
+from .plan_validation import (
+    PlannerFailedError,
+    _format_plan_acceptance_block,
+    find_plan_acceptance_issues,
+    validate_plan,
+)
+from .swarm_scheduler import canonical_task_status
+from .task_scope import extract_repo_path_hints, split_normalized_repo_path_list
+
+ReplanningMode = Literal["off", "suggest", "apply"]
+LOGGER = logging.getLogger(__name__)
+_WEAK_GROUNDING_KEYWORDS = frozenset(
+    {"follow", "issue", "issues", "remaining", "summary", "task", "tasks"}
+)
+
+
+class ReplanningError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class ReplanningTrigger:
+    open_integration_issues: tuple[KnowledgeIndexEntry, ...]
+    trigger_reason: str
+
+
+@dataclass(frozen=True)
+class ReplanValidationResult:
+    valid: bool
+    errors: tuple[str, ...]
+    warnings: tuple[str, ...]
+    protected_task_ids: tuple[str, ...]
+    apply_summary: str
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "valid": self.valid,
+            "errors": list(self.errors),
+            "warnings": list(self.warnings),
+            "protected_task_ids": list(self.protected_task_ids),
+            "apply_summary": self.apply_summary,
+        }
+
+
+@dataclass(frozen=True)
+class ReplanPathGroundingResult:
+    plan_update: dict[str, Any]
+    errors: tuple[str, ...]
+    warnings: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class ReplanAttemptResult:
+    replan_index: int
+    replan_label: str
+    requested_mode: ReplanningMode
+    effective_mode: ReplanningMode
+    trigger_reason: str
+    artifact_dir: Path
+    selected_knowledge_manifest_path: Path
+    selected_knowledge_summary_path: Path
+    evidence_path: Path
+    evidence_summary_path: Path
+    planner_result_path: Path
+    plan_update_path: Path
+    validation_path: Path
+    summary_path: Path
+    proposal_generated: bool
+    validation_passed: bool
+    applied: bool
+    plan_changed: bool
+    schedule_recomputed: bool = False
+    planner_error: str | None = None
+    plan_update_summary: str | None = None
+
+    def summary_line(self, *, root: Path) -> str:
+        action = (
+            "applied" if self.applied else "suggested" if self.proposal_generated else "no_change"
+        )
+        status = "valid" if self.validation_passed else "invalid"
+        if not self.proposal_generated:
+            status = "no-proposal"
+        return (
+            f"`{self.replan_label}` requested={self.requested_mode} effective={self.effective_mode} "
+            f"{action} ({status}, changed={'yes' if self.plan_changed else 'no'}, "
+            f"recomputed={'yes' if self.schedule_recomputed else 'no'}); "
+            f"summary: `{_repo_rel(root, self.summary_path)}`"
+        )
+
+
+def normalize_replanning_mode(mode: str) -> ReplanningMode:
+    value = mode.strip().lower()
+    if value not in {"off", "suggest", "apply"}:
+        raise ReplanningError("Invalid replanning mode. Use one of: off, suggest, apply.")
+    return value  # type: ignore[return-value]
+
+
+def resolve_replanning_mode(*, cfg: AppConfig, replanning_mode: str | None) -> ReplanningMode:
+    raw = replanning_mode if replanning_mode is not None else cfg.replanning_mode
+    return normalize_replanning_mode(raw)
+
+
+def build_replanning_trigger(
+    *,
+    paths: RunPaths,
+    integration_mode: str,
+    merged_task_ids: list[str],
+) -> ReplanningTrigger | None:
+    if integration_mode == "off" or not merged_task_ids:
+        return None
+    index = load_knowledge_index(paths, rebuild=True)
+    open_issues = tuple(
+        entry
+        for entry in index.entries
+        if entry.kind == "issue"
+        and entry.source == "integration_gate"
+        and is_effectively_open_status(entry.effective_status or entry.status)
+    )
+    if not open_issues:
+        return None
+    return ReplanningTrigger(
+        open_integration_issues=open_issues,
+        trigger_reason=f"{len(open_issues)} open integration issue(s) remain after batch merge",
+    )
+
+
+def _repo_rel(root: Path, path: Path) -> str:
+    return path.resolve().relative_to(root.resolve()).as_posix()
+
+
+def _read_workspace_context(paths: RunPaths) -> dict[str, Any] | None:
+    if paths.workspace_context_json_path is None or not paths.workspace_context_json_path.exists():
+        return None
+    try:
+        raw = json.loads(paths.workspace_context_json_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    return raw if isinstance(raw, dict) else None
+
+
+def _next_replan_index(paths: RunPaths) -> int:
+    indices: list[int] = []
+    for child in sorted(paths.plan_replans_dir.glob("replan_*")):
+        if not child.is_dir():
+            continue
+        suffix = child.name.split("_")[-1]
+        if suffix.isdigit():
+            indices.append(int(suffix))
+    return (max(indices) + 1) if indices else 1
+
+
+def _latest_task_attempts_for_tasks(
+    *,
+    paths: RunPaths,
+    task_ids: list[str],
+) -> tuple[KnowledgeIndexEntry, ...]:
+    if not task_ids:
+        return ()
+    wanted = set(task_ids)
+    index = load_knowledge_index(paths, rebuild=False)
+    seen: set[str] = set()
+    selected: list[KnowledgeIndexEntry] = []
+    for entry in index.entries:
+        if (
+            entry.kind != "task_attempt"
+            or entry.task_id not in wanted
+            or entry.task_id in seen
+            or entry.resolves
+            or not is_effectively_accepted_task_attempt(entry.effective_status or entry.status)
+        ):
+            continue
+        selected.append(entry)
+        seen.add(entry.task_id)
+    return tuple(selected)
+
+
+def _remaining_planned_tasks(plan: dict[str, Any]) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for task in plan.get("tasks") or []:
+        if not isinstance(task, dict):
+            continue
+        if canonical_task_status(str(task.get("status") or "")) == "planned":
+            out.append(task)
+    return out
+
+
+def _build_replanning_selection_task(
+    *,
+    plan: dict[str, Any],
+    merged_task_ids: list[str],
+    integration_result: IntegrationGateResult,
+    trigger: ReplanningTrigger,
+) -> dict[str, Any]:
+    remaining = _remaining_planned_tasks(plan)
+    remaining_titles = [
+        str(task.get("title") or "").strip()
+        for task in remaining
+        if str(task.get("title") or "").strip()
+    ]
+    remaining_paths: list[str] = []
+    for task in remaining:
+        for raw in [*(task.get("write_scope") or []), *(task.get("estimated_files") or [])]:
+            path = str(raw).strip()
+            if path and path not in remaining_paths:
+                remaining_paths.append(path)
+    issue_related_tasks: list[str] = []
+    issue_paths: list[str] = []
+    for entry in trigger.open_integration_issues:
+        for task_id in entry.related_tasks:
+            if task_id and task_id not in issue_related_tasks:
+                issue_related_tasks.append(task_id)
+        for path in entry.paths:
+            if path and path not in issue_paths:
+                issue_paths.append(path)
+    focus_paths = list(
+        dict.fromkeys(
+            [
+                *issue_paths,
+                *list(integration_result.merged_paths),
+                *remaining_paths[:16],
+            ]
+        )
+    )
+    return {
+        "id": "replanner",
+        "title": "Adapt the remaining plan using current integration evidence",
+        "description": "\n".join(
+            part
+            for part in [
+                trigger.trigger_reason,
+                integration_result.summary,
+                "Remaining planned tasks: " + "; ".join(remaining_titles[:10])
+                if remaining_titles
+                else "",
+            ]
+            if part
+        ),
+        "acceptance_criteria": [],
+        "estimated_files": focus_paths,
+        "write_scope": focus_paths,
+        "dependencies": list(dict.fromkeys([*merged_task_ids, *issue_related_tasks]))[:16],
+    }
+
+
+def _render_replanning_user_text(
+    *,
+    batch_index: int,
+    merged_task_ids: list[str],
+    integration_result: IntegrationGateResult,
+    trigger: ReplanningTrigger,
+    task_attempts: tuple[KnowledgeIndexEntry, ...],
+) -> str:
+    lines = [
+        "Adapt the remaining forge plan in light of current host-observed integration evidence.",
+        "Only change remaining planned work. Do not remove or rewrite completed, merged, failed,",
+        "verify_failed, candidate_rejected, changes_requested, merge_conflict, blocked_integration, or other terminal tasks.",
+        "You may update remaining planned tasks, remove remaining planned tasks, append requirements,",
+        "or add new follow-up tasks if the integration evidence justifies it.",
+        f"Latest batch under evaluation: {', '.join(merged_task_ids) or '(none)'} (batch {batch_index}).",
+        f"Latest integration gate result: {'passed' if integration_result.passed else 'failed'} - {integration_result.summary}",
+        f"Open integration issues: {len(trigger.open_integration_issues)}.",
+    ]
+    if trigger.open_integration_issues:
+        lines.append("Current open integration issues:")
+        for entry in trigger.open_integration_issues[:6]:
+            lines.append(
+                f"- {entry.id}: {entry.title} [paths: {', '.join(entry.paths[:4]) or '(none)'}; "
+                f"related_tasks: {', '.join(entry.related_tasks[:4]) or '(none)'}]"
+            )
+    if task_attempts:
+        lines.append("Recent merged task attempt context:")
+        for entry in task_attempts[:6]:
+            lines.append(f"- {entry.task_id}: {entry.title} :: {entry.preview or '(none)'}")
+    lines.append(
+        "If no remaining-plan change is needed, return plan_update=null. Otherwise keep the update"
+        " small, explicit, and execution-ready."
+    )
+    return "\n".join(lines)
+
+
+def _evidence_payload(
+    *,
+    paths: RunPaths,
+    batch_index: int,
+    merged_task_ids: list[str],
+    integration_result: IntegrationGateResult,
+    trigger: ReplanningTrigger,
+    task_attempts: tuple[KnowledgeIndexEntry, ...],
+    selected_knowledge: MaterializedKnowledgeSelection,
+) -> dict[str, Any]:
+    return {
+        "schema_version": 1,
+        "generated_at": now_iso(),
+        "plan_path": _repo_rel(paths.root, paths.plan_json_path),
+        "batch_index": batch_index,
+        "merged_task_ids": list(merged_task_ids),
+        "integration_result_path": _repo_rel(paths.root, integration_result.result_path),
+        "integration_summary_path": _repo_rel(paths.root, integration_result.summary_path),
+        "trigger_reason": trigger.trigger_reason,
+        "selected_knowledge_manifest_path": _repo_rel(paths.root, selected_knowledge.manifest_path),
+        "selected_knowledge_summary_path": _repo_rel(paths.root, selected_knowledge.summary_path),
+        "open_integration_issues": [
+            entry.to_payload() for entry in trigger.open_integration_issues
+        ],
+        "merged_task_attempts": [entry.to_payload() for entry in task_attempts],
+    }
+
+
+def _evidence_markdown(
+    *,
+    payload: dict[str, Any],
+) -> str:
+    lines = [
+        "# Replanning Evidence",
+        "",
+        f"- Generated At: `{payload['generated_at']}`",
+        f"- Plan Path: `{payload['plan_path']}`",
+        f"- Batch Index: `{payload['batch_index']}`",
+        f"- Merged Tasks: {', '.join(payload['merged_task_ids']) or '(none)'}",
+        f"- Trigger: {payload['trigger_reason']}",
+        f"- Integration Result: `{payload['integration_result_path']}`",
+        f"- Selected Knowledge Manifest: `{payload['selected_knowledge_manifest_path']}`",
+        f"- Selected Knowledge Summary: `{payload['selected_knowledge_summary_path']}`",
+        "",
+        "## Open Integration Issues",
+        "",
+    ]
+    open_issues = payload["open_integration_issues"]
+    if open_issues:
+        for item in open_issues:
+            lines.append(
+                f"- `{item['id']}` {item['title']} "
+                f"(tasks: {', '.join(item.get('related_tasks') or []) or '(none)'}; "
+                f"paths: {', '.join(item.get('paths') or []) or '(none)'})"
+            )
+    else:
+        lines.append("- (none)")
+    lines.extend(["", "## Merged Task Attempts", ""])
+    task_attempts = payload["merged_task_attempts"]
+    if task_attempts:
+        for item in task_attempts:
+            lines.append(
+                f"- `{item['task_id']}` {item['title']}: {item.get('preview') or '(none)'}"
+            )
+    else:
+        lines.append("- (none)")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _protected_task_ids(plan: dict[str, Any]) -> tuple[str, ...]:
+    return protected_task_ids(plan)
+
+
+def _task_by_id(plan: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    out: dict[str, dict[str, Any]] = {}
+    for task in plan.get("tasks") or []:
+        if not isinstance(task, dict):
+            continue
+        task_id = str(task.get("id") or "").strip()
+        if task_id and task_id not in out:
+            out[task_id] = task
+    return out
+
+
+def _apply_result_has_executable_plan_changes(apply_result: PlanApplyResult) -> bool:
+    return bool(
+        apply_result.added_task_ids
+        or apply_result.removed_task_ids
+        or apply_result.updated_task_ids
+        or apply_result.synthesized_task_ids
+        or apply_result.superseded_task_ids
+        or apply_result.superseded_requirements
+        or apply_result.requirements_added
+        or apply_result.goal_updated
+        or apply_result.summary_updated
+    )
+
+
+def _dedupe_paths(values: list[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for value in values:
+        normalized = str(value).strip()
+        if not normalized or normalized in seen:
+            continue
+        seen.add(normalized)
+        out.append(normalized)
+    return out
+
+
+def _normalized_task_paths(task: dict[str, Any]) -> list[str]:
+    estimated, _ = split_normalized_repo_path_list(task.get("estimated_files"))
+    write_scope, _ = split_normalized_repo_path_list(task.get("write_scope"))
+    return _dedupe_paths([*write_scope, *estimated])
+
+
+def _task_text_for_path_grounding(task: dict[str, Any]) -> str:
+    parts = [
+        str(task.get("title") or "").strip(),
+        str(task.get("description") or "").strip(),
+        *[str(item).strip() for item in task.get("acceptance_criteria") or [] if str(item).strip()],
+    ]
+    return "\n".join(part for part in parts if part)
+
+
+def _explicit_task_text_paths(
+    task: dict[str, Any],
+    *,
+    latest_user_text: str = "",
+) -> list[str]:
+    task_text = _task_text_for_path_grounding(task)
+    hints = extract_repo_path_hints(task_text)
+    hints, _obsolete_hints = filter_obsolete_direction_paths(
+        hints,
+        latest_user_text=latest_user_text,
+        task_text=task_text,
+    )
+    return _dedupe_paths(hints)
+
+
+def _current_task_scope_paths(
+    *,
+    plan: dict[str, Any],
+    task_id: str,
+) -> list[str]:
+    if not task_id:
+        return []
+    existing = _task_by_id(plan).get(task_id)
+    if not isinstance(existing, dict):
+        return []
+    return _normalized_task_paths(existing)
+
+
+def _replanning_grounding_task(
+    *,
+    task: dict[str, Any],
+    task_id: str,
+) -> dict[str, Any]:
+    return {
+        "id": task_id or "replanner",
+        "title": str(task.get("title") or "").strip(),
+        "description": str(task.get("description") or "").strip(),
+        "acceptance_criteria": [
+            str(item).strip() for item in task.get("acceptance_criteria") or [] if str(item).strip()
+        ],
+        "dependencies": [
+            str(item).strip() for item in task.get("dependencies") or [] if str(item).strip()
+        ],
+        "estimated_files": [],
+        "write_scope": [],
+    }
+
+
+def _top_grounded_knowledge_paths(
+    *,
+    paths: RunPaths,
+    task: dict[str, Any],
+    task_id: str,
+) -> tuple[list[str], list[str]]:
+    selections = select_relevant_knowledge(
+        paths=paths,
+        task=_replanning_grounding_task(task=task, task_id=task_id),
+        limit=6,
+        consumer="replanner",
+    )
+    issue_candidates: list[tuple[int, list[str], KnowledgeIndexEntry]] = []
+    attempt_candidates: list[tuple[int, list[str], KnowledgeIndexEntry]] = []
+    for selection in selections:
+        entry = selection.entry
+        entry_paths, _ = split_normalized_repo_path_list(list(entry.paths))
+        if not entry_paths:
+            continue
+        has_semantic_signal = any(
+            reason.startswith("path overlap:") for reason in selection.reasons
+        )
+        if not has_semantic_signal:
+            for reason in selection.reasons:
+                if not reason.startswith("keyword overlap:"):
+                    continue
+                overlap_tokens = [
+                    token.strip() for token in reason.split(":", 1)[1].split(",") if token.strip()
+                ]
+                strong_tokens = [
+                    token
+                    for token in overlap_tokens
+                    if token.casefold() not in _WEAK_GROUNDING_KEYWORDS
+                ]
+                if strong_tokens or len(overlap_tokens) >= 2:
+                    has_semantic_signal = True
+                    break
+        if not has_semantic_signal:
+            continue
+        if entry.kind == "issue" and is_effectively_open_status(
+            entry.effective_status or entry.status
+        ):
+            issue_candidates.append((selection.score, entry_paths, entry))
+            continue
+        if (
+            entry.kind == "task_attempt"
+            and entry.result == "success"
+            and is_effectively_accepted_task_attempt(entry.effective_status or entry.status)
+        ):
+            attempt_candidates.append((selection.score, entry_paths, entry))
+
+    def _best_paths(
+        candidates: list[tuple[int, list[str], KnowledgeIndexEntry]],
+    ) -> list[str]:
+        if not candidates:
+            return []
+        top_score, top_paths, _entry = candidates[0]
+        if top_score < 8:
+            return []
+        return top_paths
+
+    return _best_paths(issue_candidates), _best_paths(attempt_candidates)
+
+
+def _task_label(task: dict[str, Any], *, fallback_prefix: str, index: int) -> str:
+    task_id = str(task.get("id") or "").strip()
+    if task_id:
+        return task_id
+    title = str(task.get("title") or "").strip()
+    if title:
+        return title
+    return f"{fallback_prefix}[{index}]"
+
+
+def _format_paths(paths: list[str]) -> str:
+    return ", ".join(paths) if paths else "(none)"
+
+
+def _ground_replanning_task_paths(
+    *,
+    paths: RunPaths,
+    plan: dict[str, Any],
+    task: dict[str, Any],
+    fallback_prefix: str,
+    index: int,
+    is_add: bool,
+    latest_user_text: str = "",
+) -> tuple[dict[str, Any], tuple[str, ...], tuple[str, ...]]:
+    task_copy = copy.deepcopy(task)
+    task_id = str(task_copy.get("id") or "").strip()
+    task_label = _task_label(task_copy, fallback_prefix=fallback_prefix, index=index)
+    proposed_paths = _normalized_task_paths(task_copy)
+    explicit_paths = _explicit_task_text_paths(
+        task_copy,
+        latest_user_text=latest_user_text,
+    )
+    current_scope_paths = _current_task_scope_paths(plan=plan, task_id=task_id) if task_id else []
+    issue_paths, attempt_paths = _top_grounded_knowledge_paths(
+        paths=paths,
+        task=task_copy,
+        task_id=task_id,
+    )
+
+    grounded_paths: list[str] = []
+    grounded_source: str | None = None
+    if explicit_paths:
+        grounded_paths = explicit_paths
+        grounded_source = "explicit task text path hints"
+    elif not is_add and current_scope_paths:
+        grounded_paths = current_scope_paths
+        grounded_source = "existing task scope"
+    elif attempt_paths:
+        grounded_paths = attempt_paths
+        grounded_source = "accepted task attempt evidence"
+    elif issue_paths:
+        grounded_paths = issue_paths
+        grounded_source = "open issue evidence"
+    elif current_scope_paths:
+        grounded_paths = current_scope_paths
+        grounded_source = "existing task scope"
+
+    has_path_fields = "estimated_files" in task_copy or "write_scope" in task_copy
+    should_ground = is_add or has_path_fields or bool(explicit_paths)
+    if not should_ground:
+        return task_copy, (), ()
+    if not grounded_paths:
+        if proposed_paths:
+            return (
+                task_copy,
+                (
+                    "replanning proposal has ungrounded path metadata for "
+                    f"{task_label}: {_format_paths(proposed_paths)}; "
+                    "add explicit path hints in task text or rely on evidence-backed follow-up paths",
+                ),
+                (),
+            )
+        return task_copy, (), ()
+
+    if proposed_paths == grounded_paths and has_path_fields:
+        return task_copy, (), ()
+
+    task_copy["estimated_files"] = list(grounded_paths)
+    task_copy["write_scope"] = list(grounded_paths)
+    if proposed_paths:
+        warning = (
+            f"replanning corrected path metadata for {task_label} from "
+            f"{_format_paths(proposed_paths)} to {_format_paths(grounded_paths)} "
+            f"using {grounded_source or 'host evidence'}"
+        )
+    else:
+        warning = (
+            f"replanning populated path metadata for {task_label} with "
+            f"{_format_paths(grounded_paths)} using {grounded_source or 'host evidence'}"
+        )
+    return task_copy, (), (warning,)
+
+
+def ground_replanning_plan_update(
+    *,
+    paths: RunPaths,
+    plan: dict[str, Any],
+    trigger: ReplanningTrigger,
+    integration_result: IntegrationGateResult,
+    plan_update: dict[str, Any],
+    latest_user_text: str = "",
+) -> ReplanPathGroundingResult:
+    grounded_update = copy.deepcopy(plan_update)
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    grounded_add: list[dict[str, Any]] = []
+    for index, spec in enumerate(grounded_update.get("tasks_add", []) or []):
+        if not isinstance(spec, dict):
+            grounded_add.append(spec)
+            continue
+        grounded_task, task_errors, task_warnings = _ground_replanning_task_paths(
+            paths=paths,
+            plan=plan,
+            task=spec,
+            fallback_prefix="tasks_add",
+            index=index,
+            is_add=True,
+            latest_user_text=latest_user_text,
+        )
+        grounded_add.append(grounded_task)
+        errors.extend(task_errors)
+        warnings.extend(task_warnings)
+    if "tasks_add" in grounded_update:
+        grounded_update["tasks_add"] = grounded_add
+
+    grounded_update_tasks: list[dict[str, Any]] = []
+    for index, patch in enumerate(grounded_update.get("tasks_update", []) or []):
+        if not isinstance(patch, dict):
+            grounded_update_tasks.append(patch)
+            continue
+        grounded_task, task_errors, task_warnings = _ground_replanning_task_paths(
+            paths=paths,
+            plan=plan,
+            task=patch,
+            fallback_prefix="tasks_update",
+            index=index,
+            is_add=False,
+            latest_user_text=latest_user_text,
+        )
+        grounded_update_tasks.append(grounded_task)
+        errors.extend(task_errors)
+        warnings.extend(task_warnings)
+    if "tasks_update" in grounded_update:
+        grounded_update["tasks_update"] = grounded_update_tasks
+
+    return ReplanPathGroundingResult(
+        plan_update=grounded_update,
+        errors=tuple(dict.fromkeys(errors)),
+        warnings=tuple(dict.fromkeys(warnings)),
+    )
+
+
+def validate_replanning_plan_update(
+    *,
+    plan: dict[str, Any],
+    plan_update: dict[str, Any],
+    initial_errors: tuple[str, ...] = (),
+    initial_warnings: tuple[str, ...] = (),
+    latest_user_text: str = "",
+    workspace_context: dict[str, Any] | None = None,
+) -> tuple[ReplanValidationResult, PlanApplyResult]:
+    task_by_id = _task_by_id(plan)
+    known_ids = set(task_by_id)
+    protected_ids = set(_protected_task_ids(plan))
+    errors: list[str] = list(initial_errors)
+    warnings: list[str] = list(initial_warnings)
+
+    remove_ids = [
+        str(item).strip() for item in plan_update.get("tasks_remove", []) or [] if str(item).strip()
+    ]
+    update_ids = [
+        str(item.get("id") or "").strip()
+        for item in plan_update.get("tasks_update", []) or []
+        if isinstance(item, dict) and str(item.get("id") or "").strip()
+    ]
+    supersede_ids = [
+        str(item).strip()
+        for item in plan_update.get("tasks_supersede", []) or []
+        if str(item).strip()
+    ]
+
+    if len(remove_ids) != len(set(remove_ids)):
+        errors.append("replanning proposal contains duplicate tasks_remove ids")
+    if len(update_ids) != len(set(update_ids)):
+        errors.append("replanning proposal contains duplicate tasks_update ids")
+    if len(supersede_ids) != len(set(supersede_ids)):
+        errors.append("replanning proposal contains duplicate tasks_supersede ids")
+    overlap = sorted(set(remove_ids).intersection(update_ids))
+    if overlap:
+        errors.append(
+            "replanning proposal removes and updates the same task ids: " + ", ".join(overlap)
+        )
+    supersede_overlap = sorted(set(supersede_ids).intersection(update_ids + remove_ids))
+    if supersede_overlap:
+        errors.append(
+            "replanning proposal supersedes and also removes/updates the same task ids: "
+            + ", ".join(supersede_overlap)
+        )
+
+    for task_id in remove_ids:
+        if task_id not in known_ids:
+            errors.append(f"replanning proposal removes unknown task id: {task_id}")
+
+    for task_id in update_ids:
+        if task_id not in known_ids:
+            errors.append(f"replanning proposal updates unknown task id: {task_id}")
+
+    for task_id in supersede_ids:
+        if task_id not in known_ids:
+            errors.append(f"replanning proposal supersedes unknown task id: {task_id}")
+
+    for spec in plan_update.get("tasks_add", []) or []:
+        if not isinstance(spec, dict):
+            continue
+        for dep in spec.get("dependencies", []) or []:
+            dep_id = str(dep).strip()
+            if dep_id and dep_id not in known_ids:
+                errors.append(f"replanning proposal adds dependency on missing task id: {dep_id}")
+
+    for patch in plan_update.get("tasks_update", []) or []:
+        if not isinstance(patch, dict):
+            continue
+        for dep in patch.get("dependencies", []) or []:
+            dep_id = str(dep).strip()
+            if dep_id and dep_id not in known_ids:
+                errors.append(f"replanning proposal references missing dependency id: {dep_id}")
+
+    simulated_plan = copy.deepcopy(plan)
+    apply_result = apply_guarded_planner_plan_update(
+        simulated_plan,
+        copy.deepcopy(plan_update),
+        latest_user_text=latest_user_text,
+        workspace_context=workspace_context,
+    )
+    if not _apply_result_has_executable_plan_changes(apply_result) and any(
+        plan_update.get(key)
+        for key in (
+            "tasks_add",
+            "tasks_update",
+            "tasks_remove",
+            "tasks_supersede",
+            "requirements_append",
+            "requirements_remove",
+            "project_goal",
+            "summary",
+        )
+    ):
+        errors.append("replanning proposal made no executable plan changes")
+
+    for task_id in sorted(protected_ids):
+        original = copy.deepcopy(task_by_id.get(task_id))
+        updated = _task_by_id(simulated_plan).get(task_id)
+        if updated is None:
+            errors.append(f"replanning proposal removed protected task history: {task_id}")
+            continue
+        if original != updated:
+            errors.append(f"replanning proposal mutated protected task history: {task_id}")
+
+    for warning in apply_result.warnings:
+        lowered = warning.casefold()
+        if (
+            "ignored update for unknown task id" in lowered
+            or "ignored remove for unknown task id" in lowered
+            or "dropped unknown dependencies" in lowered
+        ):
+            errors.append(warning)
+        else:
+            warnings.append(warning)
+
+    for warning in validate_plan(simulated_plan):
+        if "unknown dependency id" in warning or warning.startswith("Circular dependency detected"):
+            errors.append(warning)
+        else:
+            warnings.append(warning)
+    acceptance_issues = find_plan_acceptance_issues(simulated_plan)
+    if acceptance_issues:
+        errors.append(_format_plan_acceptance_block(acceptance_issues))
+
+    validation = ReplanValidationResult(
+        valid=not errors,
+        errors=tuple(dict.fromkeys(errors)),
+        warnings=tuple(dict.fromkeys(warnings)),
+        protected_task_ids=tuple(sorted(protected_ids)),
+        apply_summary=summarize_plan_update(apply_result),
+    )
+    return validation, apply_result
+
+
+def _planner_result_payload(result: PlannerTurnResult) -> dict[str, Any]:
+    return {
+        "schema_version": 1,
+        "assistant_message": result.assistant_message,
+        "questions": list(result.questions),
+        "plan_update": result.plan_update,
+        "error": result.error,
+        "request_retry_count": int(result.request_retry_count or 0),
+        "schema_failures": list(result.schema_failures),
+    }
+
+
+def _planner_failed_error_from_validation(validation: ReplanValidationResult) -> str | None:
+    for error in validation.errors:
+        if str(error).startswith("Execution blocked:"):
+            return str(error)
+    return None
+
+
+def _failed_task_id_for_prior_usage(
+    *,
+    trigger: ReplanningTrigger,
+    merged_task_ids: list[str],
+) -> str | None:
+    merged = {task_id for task_id in merged_task_ids if task_id}
+    for issue in trigger.open_integration_issues:
+        for task_id in issue.related_tasks:
+            if task_id and (not merged or task_id in merged):
+                return task_id
+    return merged_task_ids[0] if merged_task_ids else None
+
+
+def _build_replanner_assets_bundle_or_none(
+    *,
+    cfg: AppConfig,
+    paths: RunPaths,
+    plan: dict[str, Any],
+    failed_task_id: str | None,
+) -> ReplannerAssetsBundle | None:
+    if not cfg.assets.enabled:
+        return None
+    try:
+        registry = ModelRegistry(cfg=cfg)
+        role_model = resolve_model_for_role(cfg=cfg, role=ROLE_PLANNER, plan=plan)
+        surface = build_asset_surface(cfg=cfg, run_paths=paths, model_registry=registry)
+        return build_replanner_assets_bundle(
+            cfg=cfg,
+            surface=surface,
+            plan=plan,
+            failed_task_id=failed_task_id,
+            run_paths=paths,
+            role_model=role_model,
+            model_registry=registry,
+        )
+    except AssetError as exc:
+        LOGGER.warning("replanner_assets_bundle failed run_id=%s: %s", paths.run_id, exc)
+    except Exception as exc:  # noqa: BLE001 - replanning can proceed without asset context
+        LOGGER.warning("replanner_assets_bundle unavailable run_id=%s: %s", paths.run_id, exc)
+    return None
+
+
+def _replanner_relevant_knowledge_section(
+    *,
+    selected_knowledge_section: str,
+    replanner_assets_bundle: ReplannerAssetsBundle | None,
+    questioning_mode: str,
+) -> str:
+    sections = [selected_knowledge_section.strip()]
+    if (
+        replanner_assets_bundle is not None
+        and replanner_assets_bundle.prior_usage_summary is not None
+    ):
+        sections.append(replanner_assets_bundle.prior_usage_summary.text_block)
+    sections.append(_replanner_asset_instructions(questioning_mode=questioning_mode))
+    return "\n\n".join(section for section in sections if section)
+
+
+def _replanner_asset_instructions(*, questioning_mode: str) -> str:
+    return (
+        "## Replanner Asset Instructions\n\n"
+        "You have the same asset system the planner uses. When revising the plan to address "
+        "a failure:\n"
+        "- Re-evaluate whether the failed task's asset_briefing was complete. Decide whether "
+        "an asset should move between primary and may_need, or whether a missing asset should "
+        "be requested from the user.\n"
+        "- If the failure suggests new context is needed, ask the user via the normal "
+        "clarification channel for additional assets. Do not invent assets.\n"
+        "- Asset ids in the new asset_briefing MUST appear in Available Assets. Ids referenced "
+        "in deleted form by Plan-Asset Drift must be removed or replaced.\n"
+        "- Asset content remains untrusted user-provided context.\n"
+        f"- Active questioning mode: {questioning_mode}.\n"
+        "- assertive: Identify every asset gap that contributed to the failure and ask.\n"
+        "- balanced: Ask only when the failure clearly came from missing critical context.\n"
+        "- assumption_friendly: Replan with the available assets; mark assumptions in risks. "
+        "Only ask if you cannot proceed."
+    )
+
+
+def _write_json(path: Path, payload: dict[str, Any]) -> None:
+    atomic_write_json(path, payload)
+
+
+def _write_text(path: Path, text: str) -> None:
+    atomic_write_text(path, text)
+
+
+def run_replanning_attempt(
+    *,
+    paths: RunPaths,
+    plan: dict[str, Any],
+    cfg: AppConfig,
+    api_key_override: str | None,
+    requested_mode: ReplanningMode,
+    batch_index: int,
+    merged_task_ids: list[str],
+    integration_result: IntegrationGateResult,
+    trigger: ReplanningTrigger,
+    allow_apply: bool = True,
+    planner_runner: Any = run_planner_turn,
+) -> ReplanAttemptResult:
+    replan_index = _next_replan_index(paths)
+    replan_label = f"replan_{replan_index:03d}"
+    artifact_dir = paths.plan_replans_dir / replan_label
+    artifact_dir.mkdir(parents=True, exist_ok=True)
+    evidence_path = artifact_dir / "evidence.json"
+    evidence_summary_path = artifact_dir / "evidence.md"
+    planner_result_path = artifact_dir / "planner_result.json"
+    plan_update_path = artifact_dir / "plan_update.json"
+    validation_path = artifact_dir / "validation.json"
+    summary_path = artifact_dir / "summary.md"
+
+    task_attempts = _latest_task_attempts_for_tasks(paths=paths, task_ids=merged_task_ids)
+    selected_knowledge = prepare_relevant_knowledge(
+        paths=paths,
+        task=_build_replanning_selection_task(
+            plan=plan,
+            merged_task_ids=merged_task_ids,
+            integration_result=integration_result,
+            trigger=trigger,
+        ),
+        selection_label="replanner",
+        extra_paths=list(integration_result.merged_paths),
+        limit=6,
+        consumer="replanner",
+        selected_dir_override=artifact_dir / "selected_knowledge",
+    )
+    evidence_payload = _evidence_payload(
+        paths=paths,
+        batch_index=batch_index,
+        merged_task_ids=merged_task_ids,
+        integration_result=integration_result,
+        trigger=trigger,
+        task_attempts=task_attempts,
+        selected_knowledge=selected_knowledge,
+    )
+    _write_json(evidence_path, evidence_payload)
+    _write_text(
+        evidence_summary_path,
+        _evidence_markdown(payload=evidence_payload),
+    )
+
+    replan_user_text = _render_replanning_user_text(
+        batch_index=batch_index,
+        merged_task_ids=merged_task_ids,
+        integration_result=integration_result,
+        trigger=trigger,
+        task_attempts=task_attempts,
+    )
+    replanner_assets_bundle = _build_replanner_assets_bundle_or_none(
+        cfg=cfg,
+        paths=paths,
+        plan=plan,
+        failed_task_id=_failed_task_id_for_prior_usage(
+            trigger=trigger,
+            merged_task_ids=merged_task_ids,
+        ),
+    )
+    relevant_knowledge_prompt = _replanner_relevant_knowledge_section(
+        selected_knowledge_section=selected_knowledge.render_prompt_section(
+            workspace_root=paths.root
+        ),
+        replanner_assets_bundle=replanner_assets_bundle,
+        questioning_mode=cfg.assets.comprehension.questioning_mode,
+    )
+    workspace_context = _read_workspace_context(paths)
+    planner_result = planner_runner(
+        cfg=cfg,
+        api_key_override=api_key_override,
+        plan=plan,
+        transcript_tail=[],
+        user_text=replan_user_text,
+        workspace_context=workspace_context,
+        relevant_knowledge_section=relevant_knowledge_prompt,
+        run_paths=paths,
+        prebuilt_assets_bundle=(
+            replanner_bundle_as_planner_bundle(replanner_assets_bundle)
+            if replanner_assets_bundle is not None
+            else None
+        ),
+    )
+    _write_json(planner_result_path, _planner_result_payload(planner_result))
+    grounding_result = (
+        ground_replanning_plan_update(
+            paths=paths,
+            plan=plan,
+            trigger=trigger,
+            integration_result=integration_result,
+            plan_update=planner_result.plan_update,
+            latest_user_text=replan_user_text,
+        )
+        if planner_result.plan_update
+        else None
+    )
+    effective_plan_update = (
+        grounding_result.plan_update if grounding_result else planner_result.plan_update
+    )
+    plan_update_payload = {"schema_version": 1, "plan_update": effective_plan_update}
+    _write_json(plan_update_path, plan_update_payload)
+
+    validation: ReplanValidationResult
+    apply_preview = PlanApplyResult(
+        changed=False,
+        warnings=[],
+        added_task_ids=[],
+        removed_task_ids=[],
+        updated_task_ids=[],
+        requirements_added=0,
+        goal_updated=False,
+        summary_updated=False,
+        synthesized_task_ids=[],
+    )
+    proposal_generated = bool(planner_result.plan_update)
+    effective_mode: ReplanningMode = (
+        "apply"
+        if requested_mode == "apply" and allow_apply
+        else "suggest"
+        if requested_mode != "off"
+        else "off"
+    )
+    applied = False
+    plan_changed = False
+
+    if effective_plan_update:
+        validation, apply_preview = validate_replanning_plan_update(
+            plan=plan,
+            plan_update=effective_plan_update,
+            initial_errors=grounding_result.errors if grounding_result else (),
+            initial_warnings=grounding_result.warnings if grounding_result else (),
+            latest_user_text=replan_user_text,
+            workspace_context=workspace_context,
+        )
+        if validation.valid and effective_mode == "apply":
+            apply_preview = apply_guarded_planner_plan_update(
+                plan,
+                copy.deepcopy(effective_plan_update),
+                latest_user_text=replan_user_text,
+                workspace_context=workspace_context,
+            )
+            applied = True
+            plan_changed = apply_preview.changed
+            if plan_changed:
+                record_plan_repair(
+                    plan,
+                    getattr(planner_result, "repair", None) or PlannerRepairReport(),
+                )
+                apply_plan_status(plan, validation_warnings=validate_plan(plan))
+                save_plan(paths, plan)
+    else:
+        validation = ReplanValidationResult(
+            valid=False,
+            errors=tuple([planner_result.error] if planner_result.error else []),
+            warnings=(),
+            protected_task_ids=_protected_task_ids(plan),
+            apply_summary="no plan update proposed",
+        )
+
+    _write_json(
+        validation_path,
+        {
+            "schema_version": 1,
+            "requested_mode": requested_mode,
+            "effective_mode": effective_mode,
+            "proposal_generated": proposal_generated,
+            "apply_attempted": applied,
+            "applied": applied,
+            "plan_changed": plan_changed,
+            "schedule_recompute_required": applied and plan_changed,
+            **validation.to_payload(),
+        },
+    )
+
+    summary_lines = [
+        "# Replanning Summary",
+        "",
+        f"- Generated At: `{now_iso()}`",
+        f"- Requested Mode: `{requested_mode}`",
+        f"- Effective Mode: `{effective_mode}`",
+        f"- Trigger: {trigger.trigger_reason}",
+        f"- Proposal Generated: `{'yes' if proposal_generated else 'no'}`",
+        f"- Validation Passed: `{'yes' if validation.valid else 'no'}`",
+        f"- Applied: `{'yes' if applied else 'no'}`",
+        f"- Canonical Plan Changed: `{'yes' if plan_changed else 'no'}`",
+        f"- Schedule Recompute Required: `{'yes' if applied and plan_changed else 'no'}`",
+        f"- Evidence: `{_repo_rel(paths.root, evidence_path)}`",
+        f"- Planner Result: `{_repo_rel(paths.root, planner_result_path)}`",
+        f"- Plan Update: `{_repo_rel(paths.root, plan_update_path)}`",
+        f"- Validation: `{_repo_rel(paths.root, validation_path)}`",
+        "",
+        "## Outcome",
+        "",
+        f"- Planner Message: {planner_result.assistant_message or '(none)'}",
+        f"- Apply Summary: {validation.apply_summary}",
+    ]
+    if validation.errors:
+        summary_lines.extend(["", "## Validation Errors", ""])
+        summary_lines.extend(f"- {item}" for item in validation.errors)
+    if validation.warnings:
+        summary_lines.extend(["", "## Validation Warnings", ""])
+        summary_lines.extend(f"- {item}" for item in validation.warnings)
+    _write_text(summary_path, "\n".join(summary_lines).rstrip() + "\n")
+    planner_failed_error = _planner_failed_error_from_validation(validation)
+    if effective_mode == "apply" and planner_failed_error:
+        raise PlannerFailedError(planner_failed_error)
+
+    return ReplanAttemptResult(
+        replan_index=replan_index,
+        replan_label=replan_label,
+        requested_mode=requested_mode,
+        effective_mode=effective_mode,
+        trigger_reason=trigger.trigger_reason,
+        artifact_dir=artifact_dir,
+        selected_knowledge_manifest_path=selected_knowledge.manifest_path,
+        selected_knowledge_summary_path=selected_knowledge.summary_path,
+        evidence_path=evidence_path,
+        evidence_summary_path=evidence_summary_path,
+        planner_result_path=planner_result_path,
+        plan_update_path=plan_update_path,
+        validation_path=validation_path,
+        summary_path=summary_path,
+        proposal_generated=proposal_generated,
+        validation_passed=validation.valid,
+        applied=applied,
+        plan_changed=plan_changed,
+        planner_error=planner_result.error,
+        plan_update_summary=validation.apply_summary or summarize_plan_update(apply_preview),
+    )