Skip to content

hashgraph-online/awesome-codex-plugins / plugins/beastlabai/multi-llm-plugin/skills/multi-llm

multi-llm

Flagged

Orchestrate plan reviews, task generation, implementation and code reviews across several LLM CLIs in parallel, or ask every model one free-text question about a plan. Use when the user says: review my plan, multi-llm, run a code review, generate tasks from a plan, implement this plan, ask the models about my plan.

FileKindSize
SKILL.mdskill md4.0 KB
apply_code_fixes_orchestrator.pyscript56.6 KB
apply_commit_fixes_orchestrator.pyscript2.3 KB
apply_suggestions_orchestrator.pyscript4.5 KB
apply_task_suggestions_orchestrator.pyscript19.1 KB
ask_orchestrator.pyscript162.5 KB
assets/icons/Anthropic.svgother584 B
assets/icons/Codex.svgother1.3 KB
assets/icons/Copilot.svgother1.5 KB
assets/icons/Cursor.svgother793 B
assets/icons/GoogleGemini.svgother623 B
assets/icons/Goose.svgother3.2 KB
assets/icons/Kilocode.svgother531 B
assets/icons/MiniMax.pngbinary1.5 KB
assets/icons/Mistral.svgother717 B
assets/icons/MoonshotAI.svgother957 B
assets/icons/Nvidia.svgother2.4 KB
assets/icons/OhMyPi.svgother434 B
assets/icons/OpenAI.svgother1.7 KB
assets/icons/Opencode.svgother325 B
assets/icons/Pi.svgother440 B
assets/icons/Qwen.svgother1.7 KB
assets/icons/Zhipu.pngbinary442 B
assets/icons/xAI.svgother343 B
assets/omp/overlay.ymlconfig2.4 KB
check_workflow_prerequisites.pyscript74.5 KB
code_review_orchestrator.pyscript324.0 KB
display_decisions.pyscript9.8 KB
finalize_tracking.pyscript1.3 KB
full_workflow_orchestrator.pyscript58.8 KB
generate_tasks_orchestrator.pyscript44.2 KB
hosts/capabilities.yamlconfig49.9 KB
hosts/codex/plugin-skill.md.tmplother2.8 KB
hosts/codex/shim.md.tmplother7.3 KB
hosts/opencode/plugin-command.md.tmplother2.2 KB
hosts/opencode/shim.md.tmplother6.8 KB
hosts/render_capabilities.pyscript48.4 KB
hosts/snippets/poll-loop.mdmarkdown4.4 KB
hosts/snippets/uv-preflight.mdmarkdown2.2 KB
hosts/uv-missing.txtmarkdown1.5 KB
implement_orchestrator.pyscript156.0 KB
improve_code_orchestrator.pyscript1.6 KB
improve_commits_orchestrator.pyscript2.5 KB
improve_plan_orchestrator.pyscript1.6 KB
init_config.pyscript57.6 KB
instructions/apply-code-fixes.mdmarkdown52.0 KB
instructions/apply-commit-fixes.mdmarkdown10.3 KB
instructions/apply-suggestions.mdmarkdown48.2 KB
instructions/apply-task-suggestions.mdmarkdown53.9 KB
instructions/ask.mdmarkdown27.6 KB
instructions/full-workflow.mdmarkdown24.6 KB
instructions/generate-tasks.mdmarkdown18.1 KB
instructions/implement.mdmarkdown54.0 KB
instructions/improve-code.mdmarkdown25.0 KB
instructions/improve-commits.mdmarkdown24.8 KB
instructions/improve-plan.mdmarkdown26.2 KB
instructions/init-config.mdmarkdown6.6 KB
instructions/review-code.mdmarkdown43.5 KB
instructions/review-commits.mdmarkdown11.4 KB
instructions/review-plan.mdmarkdown38.4 KB
instructions/review-tasks.mdmarkdown37.8 KB
modes.pyscript58.8 KB
multi_llm.pyscript101.1 KB
prompts/ask.txtmarkdown948 B
prompts/code_review.txtmarkdown4.5 KB
prompts/commit_review.txtmarkdown6.2 KB
prompts/consolidate_suggestions.txtmarkdown3.1 KB
prompts/implementation_task.txtmarkdown1.4 KB
prompts/plan_review.txtmarkdown8.0 KB
prompts/task_review.txtmarkdown8.3 KB
providers.yamlconfig19.6 KB
pyproject.tomlmanifest6.8 KB
references/apply-write-executor.mdmarkdown3.0 KB
references/consolidation.mdmarkdown5.6 KB
references/host-capabilities.mdmarkdown13.5 KB
references/human-decision-batch.mdmarkdown17.2 KB
references/implement-prerequisites.mdmarkdown6.0 KB
references/implement-write-executor.mdmarkdown4.9 KB
references/interrupted-run-recovery.mdmarkdown3.1 KB
references/own-check.mdmarkdown4.3 KB
references/resume-detection.mdmarkdown8.5 KB
references/revalidation.mdmarkdown6.9 KB
references/review-code-apply-fixes.mdmarkdown4.3 KB
references/salvage-handling.mdmarkdown12.5 KB
references/summary-format.mdmarkdown10.0 KB
references/uv-check.mdmarkdown5.7 KB
references/wave-batching.mdmarkdown5.2 KB
review_commits_orchestrator.pyscript2.3 KB
review_plan_orchestrator.pyexecutablescript22.3 KB
review_tasks_orchestrator.pyscript10.7 KB
schemas/cascade_record.schema.jsonconfig6.6 KB
schemas/code_review_issues.schema.jsonconfig2.0 KB
schemas/consolidated.schema.jsonconfig6.8 KB
schemas/consolidation_batch.schema.jsonconfig3.7 KB
schemas/generated_tasks.schema.jsonconfig3.1 KB
schemas/host_capabilities.schema.jsonconfig38.3 KB
schemas/human_decision_verdicts.schema.jsonconfig2.6 KB
schemas/result_line.schema.jsonconfig10.1 KB
schemas/review_suggestions.schema.jsonconfig2.4 KB
schemas/state_file.schema.jsonconfig21.5 KB
schemas/status_file.schema.jsonconfig24.9 KB
schemas/status_json.schema.jsonconfig10.8 KB
schemas/subagent_tasks.schema.jsonconfig20.5 KB
schemas/task_decomposition.schema.jsonconfig1.2 KB
schemas/write_batch_result.schema.jsonconfig8.8 KB
templates/config/providers.override.yamlconfig17.2 KB
templates/consolidated_report_template.htmlother44.1 KB
templates/pr_report_template.htmlother181.2 KB
templates/report_template.htmlother67.5 KB
templates/shared/report_core.cssother4.1 KB
templates/shared/report_core.jsscript25.5 KB
update_plan_tasks.pyscript20.9 KB
utils/__init__.pyscript284 B
utils/advisory.pyscript4.8 KB
utils/apply_orchestrator_base.pyscript220.6 KB
utils/apply_output_helpers.pyscript10.9 KB
utils/apply_path_helpers.pyscript683 B
utils/apply_report.pyscript51.2 KB
utils/apply_selection_helpers.pyscript6.8 KB
utils/apply_suggestion_phase.pyscript11.7 KB
utils/atomic_io.pyscript12.9 KB
utils/attempt_classifier.pyscript31.4 KB
utils/backup.pyscript2.0 KB
utils/batch_done.pyscript79.2 KB
utils/batch_ledger.pyscript27.4 KB
utils/batch_prompt.pyscript29.3 KB
utils/batch_prompt_builder.pyscript12.2 KB
utils/batch_reply.pyscript32.9 KB
utils/cascade_archive.pyscript50.6 KB
utils/cascade_ledger.pyscript39.3 KB
utils/cascade_provenance.pyscript22.0 KB
utils/check_records.pyscript59.3 KB
utils/check_reply.pyscript9.5 KB
utils/check_tree.pyscript1.2 KB
utils/cli_common.pyscript91.2 KB
utils/cli_version_cache.pyscript14.0 KB
utils/clock.pyscript3.5 KB
utils/code_fix_batcher.pyscript30.6 KB
utils/codex_trust.pyscript12.9 KB
utils/commit_apply.pyscript73.3 KB
utils/commit_attribution.pyscript21.2 KB
utils/commit_brief.pyscript32.2 KB
utils/commit_front_door.pyscript81.6 KB
utils/commit_paths.pyscript18.0 KB
utils/commit_range.pyscript61.2 KB
utils/commit_report.pyscript19.9 KB
utils/commit_review.pyscript413 B
utils/commit_spelling.pyscript7.9 KB
utils/commit_write_guard.pyscript9.9 KB
utils/concurrency.pyscript11.6 KB
utils/consolidation.pyscript87.3 KB
utils/detach.pyscript186.8 KB
utils/dispatch_spawn.pyscript56.3 KB
utils/doctor.pyscript76.7 KB
utils/env_vars.pyscript20.5 KB
utils/failure_capture.pyscript10.1 KB
utils/file_discovery.pyscript11.0 KB
utils/filtering.pyscript19.9 KB
utils/git_diff.pyscript23.6 KB
utils/git_utils.pyscript86.6 KB
utils/held_folder.pyscript21.3 KB
utils/host_capabilities.pyscript48.0 KB
utils/host_install.pyscript77.6 KB
utils/host_paths.pyscript12.0 KB
utils/host_routes/__init__.pyscript5.7 KB
utils/host_routes/codex.pyscript18.3 KB
utils/host_routes/npm.pyscript12.2 KB
utils/host_shim.pyscript14.7 KB
utils/html_report_generator.pyscript118.9 KB
utils/human_decisions.pyscript38.3 KB
utils/human_task_plan.pyscript30.2 KB
utils/importance.pyscript6.2 KB
utils/improve_cascade.pyscript63.7 KB
utils/improve_cascade_next.pyscript22.2 KB
utils/improve_steps.pyscript32.4 KB
utils/improve_workflow.pyscript114.4 KB
utils/interactive.pyscript31.6 KB
utils/json_extractor.pyscript61.5 KB
utils/judge_vocab.pyscript5.3 KB
utils/known_checks.pyscript37.5 KB
utils/landlock_dispatch.pyscript103.8 KB
utils/landlock_exec.pyscript21.4 KB
utils/launch_limiter.pyscript13.5 KB
utils/llm_client.pyscript126.9 KB
utils/manual_tasks.pyscript14.9 KB
utils/metrics.pyscript68.1 KB
utils/next_phase.pyscript96.1 KB
utils/next_phase_words.pyscript6.4 KB
utils/output_handler.pyscript23.2 KB
utils/phase_walk.pyscript6.4 KB
utils/plan_updater.pyscript17.9 KB
utils/positionals.pyscript5.8 KB
utils/prior_changes.pyscript28.7 KB
utils/probe_state.pyscript17.9 KB
utils/process_capture.pyscript37.6 KB
utils/process_control.pyscript228.7 KB
utils/process_state.pyscript6.6 KB
utils/progress_tracker.pyscript92.2 KB
utils/prompt_channels.pyscript34.1 KB
utils/prompt_files.pyscript24.5 KB

apply_code_fixes_orchestrator.py

View on GitHub
#!/usr/bin/env python3
"""
Orchestrator for applying validated code review fixes to the codebase.

This script reads validation results from a code review and outputs
the list of fixes that should be applied. The actual application
is handled by Claude Code using Task subagents sequentially.

Usage:
    uv run --project "{SKILL_DIR}" -- python "{SKILL_DIR}/multi_llm.py" apply-code-fixes plans/my-plan.md [options]
"""

import copy
import os
import re
import sys
from argparse import SUPPRESS
from datetime import datetime
from pathlib import Path
from typing import Any, Dict, List, Optional, Set, Tuple

# Add parent to path for imports
sys.path.insert(0, str(Path(__file__).parent))

from utils.stream_bootstrap import bootstrap_streams
from utils.apply_orchestrator_base import (
    VALID_OVERRIDE_VALUES,
    ApplyOrchestratorBase,
    OrchestratorError,
    build_common_arg_parser,
)
from utils.cli_common import dispatcher_prefix
from utils.judge_vocab import JUDGE_AUTO_DECIDE, JUDGE_DECIDE, canonical_value
from utils.apply_output_helpers import (
    detail_pointer_lines,
    write_and_emit_output,
)
from utils.apply_path_helpers import load_json_file
from utils.code_fix_batcher import (
    CodeFixBatch,
    batch_code_fixes,
    determine_executor_role,
    determine_subagent_type,
    estimate_batch_processing_stats,
    format_fix_batch_prompt,
)
from utils.git_utils import validate_git_ref, git_path
from utils import importance as _importance
from utils.report_parser import (
    description_edited,
    escaped_report,
    issue_numbering_digest,
    parse_issue_descriptions,
    parse_issue_numbering_digest,
    parse_skipped_issues,
    parse_validation_overrides_issues,
)
from utils.state_manager import (
    CURRENT_FORMAT_VERSION,
    load_groups_payload,
    match_issues_to_suggestions,
    stamp_stable_ids,
)
from utils.validation import (
    load_validation_results as load_validation_v2,
    bind_document_text,
    pinned_validation_guidance,
)
from utils.scope_apply import selected_remedy
from utils.commit_apply import (
    group_files,
    PROTECTED_NAMED_MAX,
    ROOT_RANGE_LINE,
    deleted_file_history,
    guard_record,
    history_lines,
    write_protected_list,
)
from utils.commit_range import DATA_UNDER_REVIEW, pinned_record
from utils.commit_front_door import hand_worker_the_stage_applier


# ---------------------------------------------------------------------------
# Standalone helpers (code-fixes-specific functions used by the subclass)
# ---------------------------------------------------------------------------


# Several report.md issues can map to one group (that is what grouping means),
# so their marks can conflict. Safety-first, the same order
# parse_validation_overrides_issues applies inside a single issue block.
_OVERRIDE_PRECEDENCE: Dict[str, int] = {
    JUDGE_DECIDE: 1,
    "valid": 2,
    "needs-human-decision": 3,
    "invalid": 4,
}


def build_issue_to_group_map(
    issues_json_path: str,
    grouped: List[Dict],
) -> Optional[Dict[int, Tuple[int, int]]]:
    """Build mapping from 1-based issue number to (1-based group_index, 1-based suggestion_index).

    Primary strategy: the content hash shared by issues.json entries and
    grouped.json members (`state_manager.match_issues_to_suggestions`), which
    tells same-hash duplicates apart by file/line and by occurrence. A plain
    `suggestion_hash` lookup used to send both copies of a word-identical
    finding in two files to the first group, so one Skip tick skipped both.
    Secondary strategy: Use `issue_index` field on suggestions in grouped.json (if available).
    Fallback strategy: Match issues.json entries to grouped.json suggestions by (title, model) pair.

    Returns None if no mapping can be built (no issues.json, no issue_index fields).
    """
    issues = load_json_file(issues_json_path)
    mapping: Dict[int, Tuple[int, int]] = {}

    if issues and isinstance(issues, list) and grouped:
        mapping = match_issues_to_suggestions(issues, grouped)
        if mapping:
            return mapping

    # Secondary strategy: use issue_index fields on suggestions in grouped.json
    mapping = {}
    has_issue_index = False
    for group_idx, group in enumerate(grouped, 1):
        for sugg_idx, sugg in enumerate(group.get("suggestions", []), 1):
            if "issue_index" in sugg:
                has_issue_index = True
                mapping[sugg["issue_index"]] = (group_idx, sugg_idx)

    if has_issue_index and mapping:
        return mapping

    # Fallback strategy: match by (title, model) pair using issues.json
    if not issues or not isinstance(issues, list):
        return None

    mapping = {}
    # Build lookup from (title, model) -> (group_idx, sugg_idx) in grouped.json
    group_lookup: Dict[Tuple[str, str], Tuple[int, int]] = {}
    for group_idx, group in enumerate(grouped, 1):
        for sugg_idx, sugg in enumerate(group.get("suggestions", []), 1):
            title = sugg.get("title", "")
            model = sugg.get("source_model", sugg.get("model", ""))
            key = (title, model)
            if key not in group_lookup:
                group_lookup[key] = (group_idx, sugg_idx)

    # Map each issue (1-based) to its group/suggestion
    for issue_num, issue in enumerate(issues, 1):
        title = issue.get("title", "")
        model = issue.get("source_model", issue.get("model", ""))
        key = (title, model)
        if key in group_lookup:
            mapping[issue_num] = group_lookup[key]

    return mapping if mapping else None


def find_edited_issue_descriptions(
    report_path: str,
    issues: List[Dict],
    issue_to_group_map: Optional[Dict[int, Tuple[int, int]]] = None,
) -> Dict[int, Tuple[str, str]]:
    """Compare report.md descriptions with issues, return edited items by index.

    Args:
        report_path: Path to code review report.md file
        issues: List of issue groups from grouped.json
        issue_to_group_map: Optional mapping from 1-based issue number to
                           (1-based group_idx, 1-based suggestion_idx).

    Returns:
        Dict mapping issue number (1-indexed) to (original_desc, edited_desc).
    """
    report_descriptions = parse_issue_descriptions(report_path)

    if not report_descriptions:
        return {}
    escaped = escaped_report(report_path)

    edited = {}

    if issue_to_group_map is not None:
        for issue_num, report_desc in report_descriptions.items():
            if issue_num not in issue_to_group_map:
                continue
            group_idx, sugg_idx = issue_to_group_map[issue_num]
            if group_idx - 1 >= len(issues):
                continue
            group = issues[group_idx - 1]
            suggestions = group.get('suggestions', [])
            if sugg_idx - 1 < len(suggestions):
                original_desc = suggestions[sugg_idx - 1].get('desc', suggestions[sugg_idx - 1].get('description', ''))
            else:
                original_desc = group.get('desc', group.get('description', ''))

            if description_edited(original_desc, report_desc, escaped=escaped):
                edited[issue_num] = (original_desc, report_desc)
    else:
        for issue_idx, issue in enumerate(issues, start=1):
            suggestions = issue.get('suggestions', [])
            if suggestions:
                original_desc = suggestions[0].get('desc', suggestions[0].get('description', ''))
            else:
                original_desc = issue.get('desc', issue.get('description', ''))

            if issue_idx in report_descriptions:
                report_desc = report_descriptions[issue_idx]
                if description_edited(original_desc, report_desc, escaped=escaped):
                    edited[issue_idx] = (original_desc, report_desc)

    return edited


def merge_edited_issue_descriptions(
    issues: List[Dict],
    edited_descriptions: Dict[int, Tuple[str, str]],
    issue_to_group_map: Optional[Dict[int, Tuple[int, int]]] = None,
) -> Tuple[List[Dict], List[Dict]]:
    """Replace desc fields with user edits, return updated issues and edit log.

    Keys in *edited_descriptions* may be any of:
      - 1-based integer issue numbers (from report.md), resolved via
        *issue_to_group_map*;
      - suggestion hashes (from HTML user_selections.json);
      - ``G<g>S<s>`` positional IDs (from HTML user_selections.json).

    All three resolve to a (group, suggestion) location. Hash/G-format
    support is required because the HTML selection path keys edits by
    suggestion_hash; without it those edits were silently dropped
    ("Applied 0 HTML-edited descriptions"). Unknown keys are skipped.

    Args:
        issues: List of issue groups with 'suggestions' arrays
        edited_descriptions: Dict mapping key -> (original, edited) tuple.
        issue_to_group_map: Optional mapping from 1-based issue number to
                           (1-based group_idx, 1-based suggestion_idx).

    Returns:
        Tuple of (updated_issues, edit_log)
    """

    updated_issues = copy.deepcopy(issues)
    edit_log = []

    # suggestion_hash -> (1-based group_num, 1-based sugg_num) for HTML keys
    hash_to_location: Dict[str, Tuple[int, int]] = {}
    for g_idx, group in enumerate(updated_issues, 1):
        for s_idx, sugg in enumerate(group.get("suggestions", []), 1):
            shash = sugg.get("suggestion_hash")
            if shash:
                hash_to_location[shash] = (g_idx, s_idx)

    def _resolve(key) -> Optional[Tuple[int, int]]:
        """Resolve an edit key to a 1-based (group_num, sugg_num)."""
        # Integer issue number via the issue map (report.md path)
        if issue_to_group_map is not None and key in issue_to_group_map:
            return issue_to_group_map[key]
        # Suggestion hash (HTML path)
        if isinstance(key, str) and key in hash_to_location:
            return hash_to_location[key]
        # G<g>S<s> positional id, or plain-int string (HTML path)
        if isinstance(key, str):
            return _parse_g_format_id(key)
        # Bare-int positional fallback when no issue map is available:
        # treat as 1-based group index, first suggestion (legacy behavior).
        if issue_to_group_map is None and isinstance(key, int):
            return (key, 1)
        return None

    for key, (original_desc, edited_desc) in edited_descriptions.items():
        location = _resolve(key)
        if location is None:
            continue
        group_idx, sugg_idx = location
        if group_idx - 1 < 0 or group_idx - 1 >= len(updated_issues):
            continue
        group = updated_issues[group_idx - 1]
        suggestions = group.get('suggestions', [])
        if 0 <= sugg_idx - 1 < len(suggestions):
            sugg = suggestions[sugg_idx - 1]
            sugg["_original_desc"] = sugg.get("desc", sugg.get("description", ""))
            sugg["desc"] = edited_desc
            sugg["_description_edited"] = True
            title = sugg.get("title", group.get("theme", "Unknown"))
        else:
            group["_original_desc"] = group.get("desc", group.get("description", ""))
            group["desc"] = edited_desc
            group["_description_edited"] = True
            title = group.get("theme", "Unknown")

        edit_log.append({
            "index": key,
            "title": title,
            "original_len": len(original_desc),
            "edited_len": len(edited_desc),
        })

    return updated_issues, edit_log


def format_fix_for_output(
    group: Dict[str, Any], index: int, *, selected_remedy: Optional[str] = None,
) -> Dict[str, Any]:
    """Format a grouped issue for output to Claude Code.

    *selected_remedy* (``--scope-policy preserve`` only, plans/
    scope-policy-and-report-tags.md §3): the one remedy validation bound to
    this group. It is then the fix's whole description — the members'
    descriptions are not concatenated in, so a remedy validation discarded
    (an extension) cannot come back as an instruction. ``None`` keeps the
    formatting exactly as before.
    """
    suggestions = group.get("suggestions", [])

    if suggestions:
        primary = suggestions[0]
        title = group.get("theme") or primary.get("title", "Unknown")
        desc = primary.get("desc", primary.get("description", ""))
        fix_type = primary.get("type", "bug")
        file_path = primary.get("file", "")
        line_range = primary.get("line_range") or []
        anchor_text = primary.get("anchor_text", "")
        importance = primary.get("importance", "MEDIUM")
    else:
        title = group.get("theme", "Unknown")
        desc = group.get("desc", group.get("description", ""))
        fix_type = group.get("type", "bug")
        file_path = group.get("file", "")
        line_range = group.get("line_range") or []
        anchor_text = group.get("anchor_text", "")
        importance = group.get("importance", "MEDIUM")

    importance = _importance.normalize(importance)

    if len(suggestions) > 1:
        all_descs = [s.get("desc", s.get("description", "")) for s in suggestions if s.get("desc") or s.get("description")]
        if all_descs:
            desc = "\n\n".join(all_descs)
    if selected_remedy:
        desc = selected_remedy

    formatted = {
        "index": index,
        # Stable group identifier so judging subagents / human-decision-batch.md
        # can reference pre-marked items for routing/recording/resume/overlay.
        "group_id": group.get("group_hash", ""),
        "title": title,
        "description": desc,
        "desc": desc,  # Keep both for compatibility
        "type": fix_type,
        "file": file_path,
        "line_range": line_range,
        "anchor_text": anchor_text,
        "importance": importance,
        "theme": group.get("theme", ""),
        "category": group.get("category", ""),
        "validation_status": group.get("validation_status", "valid"),
        "validation_reason": group.get("validation_reason", ""),
        "validation_confidence": group.get("validation_confidence", 0.0),
        "models": group.get("models", []),
        "suggestion_count": len(suggestions),
        "executor_role": determine_executor_role({
            "file": file_path,
            "type": fix_type,
            "description": desc,
            "title": title,
        }),
        "subagent_type": determine_subagent_type({
            "file": file_path,
            "type": fix_type,
            "description": desc,
            "title": title,
        }),
    }

    # Per-item routing flag: a reviewer pre-marked this group "Let the agent
    # decide" in the report. Routed to the per-item judge without prompting.
    if group.get(JUDGE_DECIDE):
        formatted["decision_mode"] = JUDGE_AUTO_DECIDE

    return formatted


def _parse_g_format_id(gid: str) -> Optional[Tuple[int, int]]:
    """Parse a G-format ID like 'G3S1' into (group_num, suggestion_num).

    Supports two formats:
    - G-format: 'G3S1' -> (3, 1)  (case-insensitive)
    - Plain integer: '3' -> (3, 1) with a stderr warning

    Returns None for unparseable, zero, or negative inputs.
    """
    if not isinstance(gid, str) or not gid.strip():
        print(
            f"WARNING: Expected string ID, got {type(gid).__name__ if not isinstance(gid, str) else repr(gid)}. Ignoring.",
            file=sys.stderr,
        )
        return None

    gid = gid.strip()

    m = re.match(r'^G(\d+)S(\d+)$', gid, re.IGNORECASE)
    if m:
        group_num = int(m.group(1))
        sugg_num = int(m.group(2))
        if group_num < 1 or sugg_num < 1:
            print(
                f"WARNING: G-format ID '{gid}' has zero/negative index. Ignoring.",
                file=sys.stderr,
            )
            return None
        return (group_num, sugg_num)

    try:
        val = int(gid)
    except (ValueError, TypeError):
        print(
            f"WARNING: Cannot parse ID '{gid}' as G-format or integer. Ignoring.",
            file=sys.stderr,
        )
        return None

    if val < 1:
        print(
            f"WARNING: Integer ID '{gid}' is zero or negative. Ignoring.",
            file=sys.stderr,
        )
        return None

    print(
        f"WARNING: Treating plain integer ID '{gid}' as G{val}S1 "
        f"(first suggestion in group {val}).",
        file=sys.stderr,
    )
    return (val, 1)


def _apply_edited_descriptions_to_groups(
    grouped: List[Dict],
    edited_descs: Dict[str, str],
) -> Tuple[int, List[Dict]]:
    """Apply edited descriptions from HTML selections to grouped issues.

    Iterates over *edited_descs*, resolves each key (by suggestion_hash first,
    then by ``_parse_g_format_id``), converts to 0-based indices, validates
    bounds, and updates the target suggestion's ``desc`` field.

    Returns:
        Tuple of (count_applied, edit_log_entries).
    """
    # Build hash->(group_num, sugg_num) lookup (1-based)
    hash_to_location: Dict[str, Tuple[int, int]] = {}
    for g_idx, group in enumerate(grouped, 1):
        for s_idx, sugg in enumerate(group.get("suggestions", []), 1):
            shash = sugg.get("suggestion_hash")
            if shash:
                hash_to_location[shash] = (g_idx, s_idx)

    count_applied = 0
    edit_log: List[Dict] = []

    for gid, new_desc in edited_descs.items():
        # Try hash-based resolution first
        if gid in hash_to_location:
            group_num, sugg_num = hash_to_location[gid]
        else:
            parsed = _parse_g_format_id(gid)
            if parsed is None:
                continue
            group_num, sugg_num = parsed

        group_idx = group_num - 1  # 0-based
        sugg_idx = sugg_num - 1    # 0-based

        # Validate group bounds
        if group_idx < 0 or group_idx >= len(grouped):
            print(
                f"WARNING: Group index {group_num} (from ID '{gid}') is out of range "
                f"(valid: 1-{len(grouped)}). Skipping edit.",
                file=sys.stderr,
            )
            continue

        group = grouped[group_idx]
        suggestions = group.get("suggestions", [])

        # Validate suggestion bounds
        if sugg_idx < 0 or sugg_idx >= len(suggestions):
            if suggestions:
                print(
                    f"WARNING: Suggestion index {sugg_num} (from ID '{gid}') is out of range "
                    f"for group {group_num} (valid: 1-{len(suggestions)}). Skipping edit.",
                    file=sys.stderr,
                )
            else:
                # No suggestions list -- try updating at group level
                current_desc = group.get("desc", group.get("description", ""))
                if current_desc == new_desc:
                    continue  # Already identical, skip
                group["_original_desc"] = current_desc
                group["desc"] = new_desc
                group["_description_edited"] = True
                count_applied += 1
                edit_log.append({
                    "id": gid,
                    "group_index": group_num,
                    "sugg_index": sugg_num,
                    "title": group.get("theme", "Unknown"),
                    "original_len": len(current_desc),
                    "edited_len": len(new_desc),
                })
                print(f"HTML edit applied to group {group_num} (no suggestions, group-level desc)", file=sys.stderr)
            continue

        target_obj = suggestions[sugg_idx]
        current_desc = target_obj.get("desc", target_obj.get("description", ""))

        # Idempotency: skip if already identical
        if current_desc == new_desc:
            continue

        target_obj["_original_desc"] = current_desc
        target_obj["desc"] = new_desc
        target_obj["_description_edited"] = True
        count_applied += 1

        title = target_obj.get("title", group.get("theme", "Unknown"))
        edit_log.append({
            "id": gid,
            "group_index": group_num,
            "sugg_index": sugg_num,
            "title": title,
            "original_len": len(current_desc),
            "edited_len": len(new_desc),
        })
        print(f"HTML edit applied to {gid} (group {group_num}, suggestion {sugg_num})", file=sys.stderr)

    return count_applied, edit_log


# ===========================================================================
# Orchestrator subclass
# ===========================================================================


class ApplyCodeFixesOrchestrator(ApplyOrchestratorBase[Dict[str, Any], CodeFixBatch]):
    """Thin subclass for the apply-fixes phase (code review fixes)."""

    # The two words are BOTH load-bearing and must not be "reconciled" away.
    #
    # `phase_name` is the phase DIRECTORY word. `{plan}/apply-fixes/` is where
    # this phase's document, prior-changes log and snapshots live;
    # `full_workflow_orchestrator.WRITE_PHASE_DIRS` maps the mode word
    # `apply-code-fixes` onto it, and `instructions/apply-code-fixes.md` tells
    # the host to run `util prior-changes append --phase "apply-fixes"` against
    # it. Renaming this breaks the directory layout and every resume path.
    phase_name = "apply-fixes"
    # `confirmation_phase_name` is the canonical PHASE word — the mode name, the
    # key `check_workflow_prerequisites.PHASE_PREREQUISITES` uses, the value the
    # executor path writes through `PHASE_BY_WRITE_KIND["apply_code_fixes"]`, and
    # the `--phase` the instruction's `util metrics` calls carry. It is therefore
    # also what `--mark-completed` persists into `phases_completed` (the base's
    # `confirmation_phase_name or phase_name` fallback in `_setup`).
    confirmation_phase_name = "apply-code-fixes"
    review_subdir = "code-review"
    item_noun = "fix"
    # "fix" + "s" reads "Fixs" on every RESULT block, summary.md heading and log
    # line the base builds arithmetically (F8) — the irregular plural the base's
    # `__init_subclass__` default can't derive on its own.
    item_noun_plural = "fixes"
    supports_revalidation = True
    supports_skip_flag = False
    # `run()` APPLIES NOTHING: it emits batch JSON and returns, and the bytes are
    # written afterwards by the host following `instructions/apply-code-fixes.md`.
    # The base therefore records the phase *started* at emit time, never
    # completed. Completion is recorded by the host's post-loop
    # `apply-code-fixes --plan-file … --mark-completed` (that instruction's final
    # step), or by `WriteBatchScheduler._finalize` under `--exec-subagents`; both
    # run only once every batch is verified. The one exception is a run with no
    # fix left to apply, which records itself completed at its no-items exit
    # (`handle_no_items_early_exit`), since no batch loop will follow it.
    # Partitioned by `file_key`, so batches MAY co-schedule — subject to
    # driver.max_concurrent_write_subagents and the disjointness check (D3h).
    write_kind = "apply_code_fixes"
    # No single target: the batches edit source files named per batch, so there is
    # nothing one `{phase}/backup.md` could hold and nothing one `applied_to`
    # artifact could name. (Each batch still snapshots its own declared set under
    # `{phase}/pre_batch/{task_id}/`, which is the restore point here.)
    has_single_write_target = False
    # The commit apply guard runs here whenever state pins reviewed endpoints
    # (plans/review-commits.md §2.7): a commit brief's `commit_range`, or a
    # plan's `head_ref` after a direct `--head-ref` review.
    guards_commit_fixes = True

    # Instance state populated by post_load_hook
    issue_to_group_map: Optional[Dict[int, Tuple[int, int]]] = None

    def write_phase_artifact(self) -> str:
        """No single shared artifact: each batch declares its own ``file_key``.

        Returning the plan path here would snapshot the wrong file for every batch
        and make the byte comparison report "unchanged" for a run that edited real
        source, so the code-fix batches carry their declared set per batch and this
        exists only to say so explicitly.
        """
        return self.plan_path

    # ----------------------------------------------------------------
    # Argument parser
    # ----------------------------------------------------------------

    @classmethod
    def parse_args(cls, argv=None):
        """Build and parse CLI arguments for apply-fixes."""
        # Printed commands, so resolved from `__file__` and never a skill-dir
        # placeholder (see review_plan_orchestrator.parse_args for why).
        run = dispatcher_prefix()
        parser = build_common_arg_parser(
            description="Prepare validated code review fixes for application",
            epilog=f"""
This orchestrator outputs a JSON list of fixes to apply.
The actual application is handled by Claude Code using Task subagents.

Example:
  {run} apply-code-fixes plans/my-plan.md

Bulk Approval Examples:
  # Auto-approve all LOW importance items
  {run} apply-code-fixes plans/my-plan.md --approve-all-low

  # Auto-approve items with validation failures (parsing errors, timeouts)
  {run} apply-code-fixes plans/my-plan.md --approve-validation-failed

  # Skip all items requiring human review
  {run} apply-code-fixes plans/my-plan.md --skip-all-human

  # Re-run validation on failed items with a different model
  {run} apply-code-fixes plans/my-plan.md --revalidate --revalidate-model cursor-agent:opus

Finalization (run by the host AFTER every batch has been applied and verified):
  {run} apply-code-fixes plans/my-plan.md --mark-completed
        """,
            include_revalidation=True,
            include_output_format=True,
            # The native path's completion write: the emit path records the
            # phase started (see above), so this flag is the ONLY way a native
            # run records `apply-code-fixes` in `phases_completed` — issued by
            # the host after the batch loop.
            include_mark_completed=True,
            include_base_ref=True,
            include_approve_validation_failed=True,
            include_revalidate_all_human=True,
            include_internal_revalidation=True,
        )
        # Code fixes uses a smaller default batch size than the common parser
        parser.set_defaults(max_batch_size=3)
        # A commit front door's `--detach` stage (plans/review-commits.md
        # §2.1), applied by the detached worker right after its lock. Hidden.
        parser.add_argument("--commit-stage", dest="commit_stage", default=None,
                            help=SUPPRESS)
        return parser.parse_args(argv)

    # ----------------------------------------------------------------
    # Hooks
    # ----------------------------------------------------------------

    def post_load_hook(self) -> None:
        """Build issue_to_group_map after loading grouped data."""
        code_review_dir = os.path.join(self.out_dir, self.review_subdir)
        issues_json_path = os.path.join(code_review_dir, "issues.json")
        self.issue_to_group_map = build_issue_to_group_map(
            issues_json_path, self.groups
        )
        self._warn_if_report_numbering_is_stale(
            os.path.join(code_review_dir, "report.md"), issues_json_path
        )

    def _warn_if_report_numbering_is_stale(
        self, report_path: str, issues_json_path: str
    ) -> None:
        """Say so when report.md's numbers index a different issues.json.

        Every `### N.` checkbox is resolved as a POSITION in issues.json, so a
        report.md kept by hand across a re-aggregation resolves each mark to
        whatever finding now sits at that number — a wrong group, with no
        warning, because the number IS in the map. The review stamps the
        ordering it numbered (`report_parser.issue_numbering_footer`); this
        compares it and warns.

        Warns only on a mismatch. A report written before the stamp existed
        carries no digest at all, and "unstamped" is not "stale".
        """
        stamped = parse_issue_numbering_digest(report_path)
        if not stamped:
            return
        issues = load_json_file(issues_json_path)
        if not issues or not isinstance(issues, list):
            return
        if issue_numbering_digest(issues) == stamped:
            return
        print(
            f"WARNING: {report_path} was numbered against a different "
            f"issues.json than the one now in {os.path.dirname(issues_json_path)} "
            f"— its issue numbers may resolve to the wrong findings. Re-run the "
            f"code review, or make selections in report.html instead (those name "
            f"group hashes, not positions).",
            file=sys.stderr,
        )

    def handle_no_items_early_exit(self) -> None:
        """Write empty output, record the phase completed and exit when no fixes remain."""
        print("\nNo fixes to apply.", file=sys.stderr)

        # Nothing left to apply is this review cycle's apply, finished: recorded
        # completed and stamped now, the record apply-suggestions writes when it
        # hands out no batch (plan improve-plan-and-improve-code §2.3, *Empty
        # apply outcomes*). This exit used to record nothing, so `full`'s
        # `_verify` read an all-invalid code review's apply as unfinished (exit
        # 3, "records no completion") or as done on the previous cycle's stamp.
        # A completion, never a skip: `mark_phase_skipped` leaves an earlier
        # cycle's completion standing, and completed wins over skipped. The
        # word is the one `--mark-completed` persists (`confirmation_phase_name`,
        # never the dir word `apply-fixes`). The hook runs before the detach
        # boundary and the executor/native fork, so both legs record it here.
        # Both dry runs stay read-only, the two-flag rule `write_target_backup`
        # applies: `--dry-run` reports and stops, and `--dry-run-subagents` is
        # a preflight ("render every command, start no child") whose record
        # would have a later real run read the phase done (Fable review
        # 2026-10-09).
        dry = getattr(self.args, "dry_run", False) or getattr(
            self.args, "dry_run_subagents", False
        )
        if not dry and self.state is not None:
            self.state.mark_phase_completed(
                self.confirmation_phase_name or self.phase_name
            )
            self.state.save()
            # A `--resume` whose step 23 dropped every group as already applied
            # is the native host that died after its last batch and before
            # `--mark-completed` (Fable review 2026-10-09): this exit is then
            # that closing call, so it says what `--mark-completed` says about
            # the repository's tests, from the same records. Its other two
            # acts need nothing here: the completion is recorded above, and
            # the plan re-stamp is only for a phase that edits the plan.
            if self.resume_dropped_groups:
                self.print_native_tests_not_run()

        phase_dir = os.path.join(self.out_dir, self.phase_name)
        os.makedirs(phase_dir, exist_ok=True)

        output = {
            "format_version": CURRENT_FORMAT_VERSION,
            "plan_file": self.plan_path,
            "prefix": self.prefix,
            "output_dir": self.out_dir,
            "timestamp": datetime.now().isoformat(),
            "batches": [],
            "to_apply": [],
            "needs_human_review": [],
            "skipped_items": self.formatted_skipped,
            "user_skipped_items": self.user_skipped_items,
            "skipped_count": len(self.skipped),
            "batching_stats": {
                "total_fixes": 0,
                "total_batches": 0,
                "subagent_calls_saved": 0,
                "efficiency_gain_percent": 0,
            },
            "summary": {
                "total_issues": len(self.groups),
                "valid_count": 0,
                "needs_human_count": 0,
                "skipped_count": len(self.skipped),
                "user_skipped_count": len(self.user_skipped_items),
                "batch_count": 0,
            }
        }

        write_and_emit_output(output, phase_dir)
        self.emit_payload(output)
        sys.exit(0)

    def _group_hash_for_issue(self, issue_num: int) -> Optional[str]:
        """Resolve a report.md issue number to the group_hash it really names.

        report.md numbers *issues* — one ``### N.`` block per model finding —
        while the checkboxes act on *groups*, and the two only line up when
        every group has exactly one member. Using the issue number as a group
        index therefore puts the user's mark on whichever finding happens to
        sit at that position: on a measured 3-model review, 11 of 12
        checkboxes hit the wrong group and three fell off the end of the list.
        ``issue_to_group_map`` (built in ``post_load_hook`` from issues.json)
        is the real mapping; a number it cannot place is warned about, never
        silently dropped.

        Returns ``None`` when the number cannot be resolved.
        """
        # merged mirrors groups one-for-one (--resume aside), so it stands in
        # for callers that have not loaded self.groups.
        groups = getattr(self, "groups", None) or getattr(self, "merged", None) or []
        mapping = self.issue_to_group_map

        if mapping is not None:
            location = mapping.get(issue_num)
            if location is None:
                print(
                    f"WARNING: report.md issue {issue_num} is not in the "
                    f"issue->group map (stale report.md, or issues.json does "
                    f"not cover it); ignoring its checkbox.",
                    file=sys.stderr,
                )
                return None
            group_idx = location[0]
        else:
            # No issues.json to map through: the legacy 1:1 reading, which is
            # correct only when no two models agreed.
            group_idx = issue_num

        if not (1 <= group_idx <= len(groups)):
            print(
                f"WARNING: report.md issue {issue_num} resolves to group "
                f"{group_idx}, outside the {len(groups)} loaded groups; "
                f"ignoring its checkbox.",
                file=sys.stderr,
            )
            return None

        ghash = groups[group_idx - 1].get("group_hash", "")
        if not ghash:
            print(
                f"WARNING: group {group_idx} (report.md issue {issue_num}) "
                f"has no group_hash; ignoring its checkbox.",
                file=sys.stderr,
            )
            return None
        return ghash

    def apply_group_validation_overrides(self) -> None:
        """Apply validation overrides keyed by report.md issue number or group hash.

        Integer keys come from ``parse_validation_overrides_issues``, i.e. the
        ``### N.`` *issue* numbers, and are resolved to their group through
        ``_group_hash_for_issue``; hash keys (HTML / consolidated decisions)
        already name a group. Two members of one group can carry conflicting
        marks, so the same safety-first precedence a single block uses applies
        across members: invalid > needs-human-decision > valid > judge_decide.
        """
        if not self.validation_overrides:
            return

        # group_hash -> (the key the user wrote, the override value)
        by_hash: Dict[str, Tuple[Any, str]] = {}
        for key, value in self.validation_overrides.items():
            value = canonical_value(value)
            if value not in VALID_OVERRIDE_VALUES:
                print(
                    f"WARNING: ignoring unknown validation override {value!r} "
                    f"for issue {key}; leaving its underlying status "
                    f"unchanged.",
                    file=sys.stderr,
                )
                continue
            if isinstance(key, int) or (isinstance(key, str) and key.isdigit()):
                ghash = self._group_hash_for_issue(int(key))
                if not ghash:
                    continue
            else:
                ghash = str(key)
            previous = by_hash.get(ghash)
            if previous is None or (
                _OVERRIDE_PRECEDENCE.get(value, 0)
                > _OVERRIDE_PRECEDENCE.get(previous[1], 0)
            ):
                by_hash[ghash] = (key, value)

        override_count = 0
        for group in self.merged:
            entry = by_hash.get(group.get("group_hash", ""))
            if entry is None:
                continue
            matched_key, value = entry
            # Route "judge_decide" as a marker, never as a status.
            if self._route_judge_decide_marker(group, matched_key, value):
                override_count += 1
                continue
            old_status = group.get("validation_status", "unknown")
            group["validation_status"] = value
            group["validation_reason"] = f"User override (was {old_status})"
            group["user_override"] = True
            override_count += 1
        if override_count:
            print(
                f"Applied {override_count} user validation overrides",
                file=sys.stderr,
            )

    def get_revalidation_document(self, review_dir: str):
        """``diff_context.txt`` as a ``diff`` source; the plan fallback as ``plan`` (2.1b).

        The diff is never named by path and never gets the "read the full
        plan" marker — an oversized one stays inline-truncated and is
        surfaced. Only when the file is missing does the plan stand in, and it
        is then labelled a plan (bound like any plan revalidation), so the
        prompt says which document it actually carries.
        """

        code_review_dir = os.path.join(self.out_dir, self.review_subdir)
        context_path = os.path.join(code_review_dir, "diff_context.txt")
        if os.path.exists(context_path):
            with open(context_path, 'r', encoding='utf-8') as f:
                return bind_document_text(f.read(), label="diff")
        print("Warning: diff_context.txt not found, using plan content", file=sys.stderr)
        return super().get_revalidation_document(review_dir)

    def get_revalidation_instructions(self) -> Optional[str]:
        """The code-review validation guidance for a review pinned to two commits.

        A commit review (``commit_range``) or a direct ``--head-ref`` one
        (``head_ref``) judged its findings against code read at ``head``; its
        revalidators must too, with the pinned-head read rule and the
        data-under-review sentence beside it (plans/review-commits.md §2.5,
        §2.6). That holds whatever document the batches carry as context: the
        plan fallback is what they carry in practice, since nothing writes
        ``diff_context.txt``, and the base derivation only reaches the
        guidance for a ``diff``. ``""`` when nothing is pinned, which leaves an
        unpinned revalidation's prompts as they were.
        """

        return pinned_validation_guidance(str(self.plan_path))

    def get_revalidation_context(self) -> str:
        """Return diff_context.txt contents for revalidation, falling back to plan."""
        code_review_dir = os.path.join(self.out_dir, self.review_subdir)
        context_path = os.path.join(code_review_dir, "diff_context.txt")
        if os.path.exists(context_path):
            with open(context_path, 'r', encoding='utf-8') as f:
                return f.read()
        # Fallback to plan content
        print("Warning: diff_context.txt not found, using plan content", file=sys.stderr)
        with open(self.plan_path, 'r', encoding='utf-8') as f:
            return f.read()

    def resolve_base_ref(self) -> str:
        """Resolve git base ref from --base-ref arg or state head_at_start.

        Used by the base class ``handle_revalidation()`` and by
        ``generate_batch_prompts()`` to provide diff context.

        When state pins reviewed endpoints (``commit_range``, or ``head_ref``
        after a direct ``--head-ref`` review), the base is their recorded
        base, resolved strictly in ``_setup`` (the empty-tree id on a root
        range): never ``head_before_implement``, ``head_at_start`` or
        ``validate_git_ref``'s ``HEAD~1`` fallback (plans/review-commits.md
        §2.4, §2.7). So ``git diff {base_ref} -- <file>`` in every fix prompt
        is ``git diff base head -- <file>`` for each file the guard lets
        through.

        Returns:
            A validated git ref string, or empty string.
        """
        pinned = getattr(self, "_pinned", None)
        if pinned is not None:
            return pinned.base_ref
        base_ref = getattr(self.args, "base_ref", None)
        if not base_ref:
            base_ref = (
                (self.state.get("head_before_implement") or self.state.get("head_at_start"))
                if self.state else None
            ) or "HEAD~1"
        return validate_git_ref(base_ref)

    # ----------------------------------------------------------------
    # Abstract method implementations
    # ----------------------------------------------------------------

    def load_data(self) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
        """Load grouped issues and validation from code-review subdir."""
        code_review_dir = os.path.join(self.out_dir, self.review_subdir)
        grouped_path = os.path.join(code_review_dir, "grouped.json")
        validation_path = Path(code_review_dir) / "validation.json"

        raw_grouped = load_json_file(grouped_path)
        if raw_grouped is None:
            print(f"ERROR: Grouped issues not found at {grouped_path}", file=sys.stderr)
            print("Run --review-code first to generate code review results.", file=sys.stderr)
            raise OrchestratorError(
                f"Grouped issues not found at {grouped_path}. "
                "Run --review-code first to generate code review results.",
                exit_code=1,
            )
        groups = load_groups_payload(raw_grouped)
        stamp_stable_ids(groups)

        # Load validation results (using v2 loader with migration)
        if validation_path.exists():
            # The bytes whose round step 9a checked (`held_verdicts`).
            validation = load_validation_v2(
                validation_path, raw=self.held_verdicts(validation_path))
        else:
            print("WARNING: Validation results not found, treating all as needs-human-decision", file=sys.stderr)
            validation = []

        # No "Loaded N groups"/"Loaded N validation results" print here: the
        # base's own `_load_and_parse_inputs` (step 11) announces both right
        # after `load_data()` returns. This method used to print them too, so a
        # single load announced itself twice under two different nouns ("issue
        # groups" here, "fix groups" from the base) — same two facts, four lines
        # (minor, apply-code-fixes audit, 2026-09-16).
        return groups, validation

    def parse_user_edits(self, report_path: str) -> Dict[int, Tuple[str, str]]:
        """Detect and return user-edited descriptions from report.md.

        Uses issue-number-based find_edited_issue_descriptions.
        """
        return find_edited_issue_descriptions(
            report_path, self.groups, self.issue_to_group_map
        )

    def merge_user_edits(
        self,
        groups: List[Dict[str, Any]],
        edited_descriptions,
    ) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
        """Merge issue-number-based edited descriptions."""
        return merge_edited_issue_descriptions(
            groups, edited_descriptions, self.issue_to_group_map
        )

    def parse_skips_from_report(
        self, report_path: str
    ) -> Tuple[Set[str], Set[str], Set[str]]:
        """Parse skipped issues from report.md.

        ``parse_skipped_issues`` returns *issue* numbers (the ``### N.``
        headings), which are resolved to the group each issue belongs to
        before they become the group_hash strings the base class filters on.
        Skipping one member skips its whole group: the members are the same
        finding seen by different models, so there is no partial fix to apply
        (report.md names the siblings on each block for exactly that reason).
        """
        skipped_issue_numbers = parse_skipped_issues(report_path)
        skipped_suggestion_ids: Set[str] = set()

        # Convert issue numbers to the hash-based Set[str] the base wants
        skipped_group_hashes: Set[str] = set()
        for key in skipped_issue_numbers:
            if isinstance(key, int):
                ghash = self._group_hash_for_issue(key)
                if ghash:
                    skipped_group_hashes.add(ghash)
            elif isinstance(key, str):
                skipped_group_hashes.add(key)

        return skipped_group_hashes, skipped_suggestion_ids, set()

    def parse_validation_overrides_from_report(
        self, report_path: str
    ) -> Tuple[Dict[str, str], Dict[str, str]]:
        """Parse validation overrides from report.md.

        Returns integer-key (as string) overrides for code-fixes.
        """
        md_validation_overrides = parse_validation_overrides_issues(report_path)
        # Return as group-level overrides (integer keys preserved), no per-suggestion overrides
        return md_validation_overrides, {}

    def format_item_for_output(self, group: Dict[str, Any], index: int) -> Dict[str, Any]:
        """Format a grouped issue for output, including executor_role routing.

        On a pinned run (a commit review's apply) the fix also carries
        ``files``: every distinct file its group's suggestions name, in git's
        form, primary first. Those are the batch's declared targets the
        pre-dispatch re-check and the protected-set check read (§2.7); a
        plan's run keeps its shape byte for byte.
        """

        remedy = selected_remedy(group, self.scope_gate.policy)
        formatted = format_fix_for_output(group, index, selected_remedy=remedy)
        if getattr(self, "_pinned", None) is not None:
            formatted["files"] = group_files(group, repo_root=self._repo_root)
        # Under `--scope-policy preserve`: the fix's validated scope, its
        # original descriptions kept as evidence in the output JSON only.
        return self.scope_annotate(
            formatted, group,
            original_description=(
                format_fix_for_output(group, index)["description"] if remedy else None),
        )

    def create_batches(self, items: List[Dict[str, Any]]) -> List[CodeFixBatch]:
        """Create batches from formatted fixes."""
        if getattr(self.args, "no_batch", False):
            batches = [
                CodeFixBatch(
                    fixes=[f],
                    file_key=f.get("file", "unknown"),
                    batch_type=f.get("type", "bug"),
                    executor_role=f.get("executor_role", "agent"),
                    subagent_type=f.get("subagent_type", "general-purpose"),
                    total_chars=len(f.get("description", ""))
                )
                for f in items
            ]
            self.batching_stats = {
                "total_fixes": len(items),
                "total_batches": len(items),
                "subagent_calls_saved": 0,
                "efficiency_gain_percent": 0,
                "batching_enabled": False,
            }
        else:
            batches = batch_code_fixes(
                items,
                max_per_batch=getattr(self.args, "max_batch_size", 3),
            )
            self.batching_stats = estimate_batch_processing_stats(batches)
            self.batching_stats["batching_enabled"] = True

        print("\nBatching results:", file=sys.stderr)
        print(f"  Total fixes: {self.batching_stats.get('total_fixes', 0)}", file=sys.stderr)
        print(f"  Total batches: {self.batching_stats.get('total_batches', 0)}", file=sys.stderr)
        if self.batching_stats.get("batching_enabled"):
            print(f"  Subagent calls saved: {self.batching_stats.get('subagent_calls_saved', 0)}", file=sys.stderr)
            print(f"  Efficiency gain: {self.batching_stats.get('efficiency_gain_percent', 0)}%", file=sys.stderr)
            if self.batching_stats.get("subagent_distribution"):
                print(f"  Subagent distribution: {self.batching_stats.get('subagent_distribution')}", file=sys.stderr)

        return batches

    def generate_batch_prompts(self, batches: List[CodeFixBatch]) -> List[Dict[str, Any]]:
        """Attach fix-specific prompts to each batch.

        Returns a list of dicts (batch.to_dict() + prompt) for output assembly.
        """
        # Resolve base_ref using the shared hook (consistent with handle_revalidation)
        base_ref = self.resolve_base_ref()
        print(f"Git base reference: {base_ref or '(empty - validation will lack diff context)'}", file=sys.stderr)

        # Store base_ref for use in build_output_json
        self._base_ref = base_ref

        commit_prompt = self._commit_prompt_context()
        result = []
        for i, batch in enumerate(batches):
            # output_dir carries the implement phase's own prior_changes.jsonl
            # record into the prompt (F3) — a finding is judged against the
            # plan, but nothing judged it against what implement deliberately
            # did, which is how a fix batch reverted a logged, plan-satisfying
            # tune ("accel tuned 28->32 for <4s") that a later finding, judged
            # only against the plan's other half, called a deviation.
            prompt = format_fix_batch_prompt(
                batch, self.plan_path, base_ref,
                # `out_dir` is set by `_setup()`; a prompt built before that
                # (tests, or a caller that only formats) simply has no record.
                output_dir=getattr(self, "out_dir", None),
                **(commit_prompt(batch, base_ref) if commit_prompt else {}),
            )
            # `batch_index` matches the value `write_phase_bridge`'s
            # `_apply_code_fixes_task` assigns the same batch under
            # `--exec-subagents` (0-based, dispatch/array order) — write_tasks.json
            # already carries it; orchestrator_output.json did not, so a native-leg
            # agent following "for each batch (index N)" had to derive it from
            # position (minor, apply-code-fixes audit, 2026-09-16).
            result.append({**batch.to_dict(), "prompt": prompt, "batch_index": i})
        return result

    def _commit_prompt_context(self):
        """On a pinned run, a function giving each batch's commit-review
        prompt arguments; ``None`` on a plan's run (prompts unchanged).

        Each batch's prompt then names, in ``code_only_rule``, the context
        plan (``commit_range.plan``) and the protected paths (the first 20,
        and ``apply-fixes/protected_paths.txt`` holding them all when there
        are more), and carries the reviewed range's notes: the root-range
        line, the history of each fix file absent at ``head``
        (``git show <deleting>^:<path>``), and the §2.6 trust sentence
        (plans/review-commits.md §2.7).
        """
        pinned = getattr(self, "_pinned", None)
        if pinned is None or self.state is None:
            return None

        root = self._repo_root or os.getcwd()
        record = pinned_record(self.state.state) or {}
        context_plan = None
        if self._pinned_source == "commit_range" and record.get("plan"):
            context_plan = git_path(str(record["plan"]), repo_root=root)
        guard = guard_record(self.state.state) or {}
        protected = sorted(guard.get("protected") or {})
        protected_list = None
        if len(protected) > PROTECTED_NAMED_MAX:
            written = write_protected_list(
                os.path.join(self.out_dir, self.phase_name), protected)
            protected_list = git_path(written, repo_root=root)
        # Files absent at `head` (deleting commit or None), asked once per file.
        absent: Dict[str, Optional[str]] = {}
        asked: Set[str] = set()

        def arguments(batch: CodeFixBatch, base_ref: str) -> Dict[str, Any]:
            files: List[str] = []
            for fix in batch.fixes:
                files.extend(fix.get("files") or [fix.get("file") or ""])
            names = [name for name in dict.fromkeys(files) if name]
            unknown = [name for name in names if name not in asked]
            if unknown:
                absent.update(deleted_file_history(pinned.base, pinned.head, unknown, cwd=root))
                asked.update(unknown)
            history = {name: absent[name] for name in names if name in absent}
            notes: List[str] = []
            if pinned.base is None:
                notes.append(ROOT_RANGE_LINE.format(base_ref=base_ref))
            notes.extend(history_lines(pinned.base, pinned.head, history))
            notes.append(DATA_UNDER_REVIEW)
            return {
                "context_plan": context_plan,
                "protected": protected,
                "protected_head": pinned.head,
                "protected_list": protected_list,
                "commit_notes": notes,
            }

        return arguments

    def build_output_json(
        self,
        batches: List[Any],
        *,
        resume_info: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """Assemble the final orchestrator_output.json payload."""
        phase_dir = os.path.join(self.out_dir, self.phase_name)
        os.makedirs(phase_dir, exist_ok=True)

        state_file = os.path.join(self.out_dir, "state.json")
        base_ref = getattr(self, "_base_ref", "")

        return {
            "format_version": CURRENT_FORMAT_VERSION,
            "plan_file": self.plan_path,
            "prefix": self.prefix,
            "output_dir": self.out_dir,
            "state_file": state_file,
            "base_ref": base_ref,
            "timestamp": datetime.now().isoformat(),
            "batches": batches,
            "to_apply": self.formatted_valid,
            "needs_human_review": self.formatted_human,
            "skipped_items": self.formatted_skipped,
            "user_skipped_items": self.user_skipped_items,
            "skipped_count": len(self.skipped),
            "batching_stats": self.batching_stats,
            "human_review_config": self.build_human_review_config(),
            "resume_info": resume_info,
            "edited_descriptions": self.edit_log,
            "summary": {
                "total_issues": len(self.groups),
                "valid_count": len(self.valid),
                "needs_human_count": len(self.needs_human),
                "skipped_count": len(self.skipped),
                "user_skipped_count": len(self.user_skipped_items),
                "batch_count": len(batches),
                "validation_failed_count": sum(
                    1 for g in self.merged if g.get("validation_status") == "validation_failed"
                ),
                "auto_approved_count": sum(
                    1 for g in self.valid if g.get("auto_approved", False)
                ),
                "edited_description_count": len(self.edit_log),
            },
        }

    def get_output_path(self) -> str:
        """Return path for orchestrator_output.json.

        Uses self.out_dir (which includes the double-nesting guard from
        find_output_dir) rather than get_phase_dir (which uses the
        unguarded get_output_dir and can double-nest).
        """
        phase_dir = os.path.join(self.out_dir, self.phase_name)
        os.makedirs(phase_dir, exist_ok=True)
        return os.path.join(phase_dir, "orchestrator_output.json")

    def print_text_summary(self, batches: List[Any], output_path: str) -> None:
        """Print the human-readable summary (``emit_summary`` owns JSON)."""
        base_ref = getattr(self, "_base_ref", "")

        print(f"\n{'='*60}")
        print("CODE FIXES TO APPLY (BATCHED)")
        print(f"{'='*60}")
        print(f"{self._document_title()}: {self.plan_path}")
        print(f"Valid fixes: {len(self.valid)}")
        print(f"Batches: {len(batches)}")
        print(f"Needs human review: {len(self.needs_human)}")
        print(f"Skipped: {len(self.skipped)}")
        print(f"Base ref: {base_ref}")

        if self.batching_stats.get("batching_enabled"):
            print("\nBatching efficiency:")
            print(f"  Subagent calls saved: {self.batching_stats.get('subagent_calls_saved', 0)}")
            print(f"  Efficiency gain: {self.batching_stats.get('efficiency_gain_percent', 0)}%")

        # The counts only: each batch's fixes are in the files named here, and
        # `util decisions` shows them to the user (instructions, step 3).
        print()
        for line in detail_pointer_lines(output_path):
            print(line)


def main(argv=None) -> int:
    """Main entry point."""
    bootstrap_streams()

    # A worker started here directly (apply-commit-fixes --detach) applies its
    # stage as the dispatcher's does.
    hand_worker_the_stage_applier(argv)
    args = ApplyCodeFixesOrchestrator.parse_args(argv)
    orchestrator = ApplyCodeFixesOrchestrator(args)
    return orchestrator.run()


if __name__ == "__main__":
    from utils import process_control

    # A process entry of its own: provider children must stay this process's.
    process_control.restore_sigchld_default()
    sys.exit(main(sys.argv[1:]))
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall