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

utils/apply_report.py

View on GitHub
"""The executor leg's closing report of one apply phase.

What an apply phase prints, writes and hands back once its write batches
ran: the outcome block, ``{phase}/summary.md``, the notes a host relays,
the artifact record, the ``summary_file`` patch of the batch report and the
decisions overlay on the review report. :class:`ApplyPhaseReport` reads only
the data it is built with (``ApplyOrchestratorBase.phase_report`` gathers
it), so it changes nothing on the phase that built it. See
docs/development/write-scheduler.md and docs/development/review-results.md.
"""

from __future__ import annotations

import json
import logging
import os
from dataclasses import dataclass, field
from datetime import datetime
from pathlib import Path
from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple

from .cli_common import record_artifacts
from .human_decisions import (
    is_judge_source,
    judge_outcome,
    judge_source_label,
    judge_status_label,
)
from . import scope_apply as _scope
from .state_manager import StateManager
from .text_clip import join_clauses
from .unattended import AGENT_DECIDE_FLAG
from . import detach as _detach
from . import cli_common as _cli
from . import run_record as _run_record
from . import failure_capture
from .git_utils import find_git_entry_root
from .batch_ledger import touched_files
from .write_safety import repo_root_for_report
from .task_outcome import batch_report_path
from .batch_reply import (
    batch_check_could_not_run,
    row_batch_check_findings,
    row_declined,
    DECLINED_SECTION_HEADING,
    SKIPPED_SECTION_HEADING,
)
from .check_records import batch_check_summary, batch_check_section
from .verification_lines import verification_line
from .batch_prompt import CODE_WRITE_KINDS
from .commit_spelling import commit_view
from .commit_apply import guard_record
from .html_report_generator import (
    regenerate_report_with_human_decisions,
    scope_regeneration_needed,
)


def applied_to_label(target: Optional[str], plan_path: str) -> Optional[str]:
    """The single file a phase edits (*target*), relative to the repository
    root above *plan_path*, or ``None`` without one."""
    if not target:
        return None
    try:
        # The `.git` holder above the plan, walked (no git runs here).
        start = os.path.dirname(os.path.realpath(plan_path))
        root = os.path.realpath(find_git_entry_root(start) or start)
        relative = os.path.relpath(os.path.realpath(target), root)
    except (OSError, ValueError):
        return target
    # A label in prose and in the result line: `/` on every platform.
    return target if relative.startswith(os.pardir) else relative.replace(os.sep, "/")


def _no_warnings() -> List[str]:
    return []


def _no_base_ref() -> str:
    return ""


def _plan_word() -> str:
    return "Plan"


@dataclass
class ApplyPhaseReport:
    """One apply phase's closing report, over the data it is built with.

    The phase's configuration, its work sets, the write executor's result
    and materialized tasks, its scope deferrals, and three answers the phase
    gives through its own hooks (``consistency_warnings``,
    ``resolve_base_ref`` and the document's title), read when a report
    needs them.
    """

    phase_name: str
    write_kind: str
    item_noun: str
    item_noun_plural: str
    plan_path: str
    out_dir: str
    review_subdir: str = ""
    #: The write scheduler's ``SchedulerResult``, or ``None`` before it ran.
    write_result: Optional[Any] = None
    #: The materialized write tasks, in batch order.
    write_tasks: List[Dict[str, Any]] = field(default_factory=list)
    #: The batch dicts the tasks were materialized from.
    batches: List[Any] = field(default_factory=list)
    batching_stats: Dict[str, Any] = field(default_factory=dict)
    formatted_valid: List[Dict[str, Any]] = field(default_factory=list)
    formatted_human: List[Dict[str, Any]] = field(default_factory=list)
    formatted_skipped: List[Dict[str, Any]] = field(default_factory=list)
    #: This run's scope deferrals and the earlier ones an ``expand`` released.
    scope_deferred: Sequence[Dict[str, Any]] = ()
    scope_released: Sequence[str] = ()
    state: Optional[StateManager] = None
    #: The reviewed endpoints state pins (``commit_range.Resolved``), if any.
    pinned: Optional[Any] = None
    #: The review report :meth:`regenerate_decisions_overlay` rewrote, once it has.
    decisions_overlay_path: Optional[str] = None
    #: The single file the phase overwrites (``write_target_file``), if any.
    target_file: Optional[str] = None
    consistency_warnings: Callable[[], List[str]] = _no_warnings
    resolve_base_ref: Callable[[], str] = _no_base_ref
    #: ``Plan``, or ``Commit brief`` on a commit review.
    document_title: Callable[[], str] = _plan_word
    logger: logging.Logger = field(
        default_factory=lambda: logging.getLogger("orchestrator.apply_report"))

    def _scope_summary_lines(self, *, markdown: bool = False) -> List[str]:
        return _scope.summary_lines(
            self.scope_deferred, self.scope_released, markdown=markdown)

    def touched_files(self) -> List[str]:
        """The files the write batches actually verified changed (F7).

        The observed post-run byte comparison, not the runner's own claim — the
        same set each applied or partially applied outcome's ``files_touched``
        carries. Partial application stops the run but preserves its edits,
        so those files must remain visible for inspection. Repo-root-
        relative, order-preserving, de-duplicated across every outcome; empty
        before the write executor has run, or when every batch was a no-op /
        clean failure. This is the only "what did this phase change" answer for
        a phase with no single write target (``has_single_write_target`` False —
        apply-code-fixes partitions by ``file_key``), and it is honest for the
        single-target phases too since it reflects what actually moved rather
        than the phase's own convention.

        Read from :meth:`_phase_rows`, so a ``--resume`` still names the files
        an earlier run of this phase changed (``batch_ledger.touched_files``,
        partial applications included).
        """

        return touched_files(self._phase_rows(), include_partial=True)

    def _phase_rows(self) -> List[Dict[str, Any]]:
        """Every batch row of this phase, earlier runs' first (#28).

        The scheduler's own ``report_rows()``, the rows
        ``write_batch_report.json`` carries, so ``summary.md``, the result
        block and the report cannot disagree. On a ``--resume`` they include
        the rows an interrupted run of this review cycle recorded, flagged
        ``from_earlier_run``, and never rows of an earlier cycle (the
        scheduler drops a report that predates the review). Built from this
        run's outcomes when the result has no rows of its own.
        """
        result = self.write_result
        report_rows = getattr(result, "report_rows", None)
        if callable(report_rows):
            return [dict(row) for row in report_rows()]
        rows: List[Dict[str, Any]] = []
        for outcome in getattr(result, "outcomes", None) or []:
            rows.append({
                "task_id": str(getattr(outcome, "task_id", "")),
                "status": getattr(outcome, "status", None),
                "write_outcome": getattr(outcome, "write_outcome", None),
                "runner": getattr(outcome, "runner", None),
                "duration_seconds": getattr(outcome, "duration_seconds", 0.0),
                "reason": getattr(outcome, "reason", None),
                "files_touched": list(getattr(outcome, "files_touched", None) or []),
                "output_path": getattr(outcome, "output_path", None),
                "expected_ids": list(getattr(outcome, "expected_ids", None) or []),
                "skipped": bool(getattr(outcome, "skipped", False)),
                **(
                    {"batch_check": {
                        "passed": not outcome.batch_check,
                        "findings": list(outcome.batch_check),
                    }}
                    if getattr(outcome, "batch_check", None) is not None else {}
                ),
            })
        return rows

    @staticmethod
    def _row_ok(row: Dict[str, Any]) -> bool:
        return row.get("status") == "ok"

    def _row_item_ids(self, row: Dict[str, Any]) -> List[str]:
        """The items a row's batch carried: the row's own ``expected_ids``,
        else this run's materialized task of the same id."""
        own = row.get("expected_ids")
        if own:
            return [str(item) for item in own]
        for task in self.write_tasks:
            if str(task.get("task_id", "")) == str(row.get("task_id", "")):
                return [str(item) for item in task.get("expected_ids") or []]
        return []

    @staticmethod
    def _row_provenance(row: Dict[str, Any]) -> str:
        """The marker a row from before this run carries, else ``""``."""
        if row.get("from_earlier_run"):
            return " (earlier run)"
        if row.get("skipped"):
            # A resume skip whose earlier row the scheduler could not supply
            # (that run left no report, or its report belonged to an earlier
            # review): this run reused the result file and dispatched nothing.
            return " (earlier result, not dispatched again)"
        return ""

    def _rows_provenance_note(self, rows: List[Dict[str, Any]]) -> str:
        """`` (N from an earlier run of this phase, …)`` for a count line."""
        earlier = sum(1 for row in rows if row.get("from_earlier_run"))
        reused = sum(
            1 for row in rows
            if row.get("skipped") and not row.get("from_earlier_run")
        )
        parts = []
        if earlier:
            parts.append(f"{earlier} from an earlier run of this phase")
        if reused:
            parts.append(f"{reused} earlier result(s) reused")
        if not parts:
            return ""
        return f" ({', '.join(parts)}, not dispatched again)"

    def _items_by_member_id(self) -> Dict[str, Dict[str, Any]]:
        """``member id -> formatted item`` over this run's batches.

        Each materialized task's ``expected_ids`` are its batch's items in
        order (``write_phase_bridge``), so an earlier run's row, whose
        positional id may now name another batch, still finds its own items.
        """
        items: Dict[str, Dict[str, Any]] = {}
        for task, batch in zip(self.write_tasks, self.batches):
            if not isinstance(batch, dict):
                continue
            members = self._batch_member_items(batch)
            for member_id, item in zip(task.get("expected_ids") or [], members):
                items.setdefault(str(member_id), item)
        return items

    def record_write_artifacts(self, output_path: str) -> None:
        """Hand back the files this phase produced, on the executor leg.

        A fully successful detached run reported ``artifacts: []`` and no
        ``output_files``: the phase that rewrote the plan never named the plan,
        its own output JSON, its batch report or the prior-changes log, so the
        host was left to glob a phase dir or mine a log it cannot see. Same two
        channels the review base writes — ``record_output_files`` feeds
        ``.status.json`` for ``status``, ``record_artifacts`` feeds the terminal
        ``MULTI_LLM_RESULT`` line every host is told to trust — and both drop
        paths that do not exist, so a stopped run names only what it produced.

        F7: also names every file the batches verified changed
        (``touched_file_{n}``, resolved against the same
        ``write_safety.resolve_repo_root`` anchor the scheduler pins the write
        path to — mirrors ``implement_orchestrator._record_implement_write_
        artifacts``), plus the judge's own dispatch report and the review report
        this run's decisions overlay rewrote, when either exists.
        """
        phase_dir = os.path.join(self.out_dir, self.phase_name)
        paths: Dict[str, str] = {}
        target = self.target_file
        if target:
            paths["applied_to"] = target
        paths["orchestrator_output"] = output_path
        report_path = getattr(self.write_result, "report_path", None)
        paths["write_batch_report"] = report_path or os.path.join(
            phase_dir, "write_batch_report.json"
        )
        paths["prior_changes"] = os.path.join(self.out_dir, "prior_changes.jsonl")
        # The summary report this leg writes itself (F3). Dropped like every
        # other path when absent, so `--dry-run-subagents` names no report.
        paths["summary"] = os.path.join(phase_dir, "summary.md")

        repo_root = repo_root_for_report(self.plan_path)
        for index, touched_path in enumerate(self.touched_files(), start=1):
            resolved = (
                touched_path if os.path.isabs(touched_path)
                else os.path.join(repo_root, touched_path)
            )
            paths[f"touched_file_{index}"] = resolved

        # The judge's own dispatch report, kind-qualified because a judge
        # dispatch can share this phase dir with the later write dispatch
        # (KINDS_SHARING_A_WRITE_PHASE_DIR) — otherwise invisible to a host
        # that only reads this run's `output_files`. Asked of the executor
        # rather than spelled out here (F6, 2026-09-17): it owns the naming
        # rule, and a hand-typed copy would drop this key on the day it moves.
        judge_report = batch_report_path(phase_dir, "human_decision_judge")
        if os.path.exists(judge_report):
            paths["human_decision_judge_report"] = judge_report

        # The review report this phase's own decisions overlay just rewrote,
        # if any (`regenerate_decisions_overlay`, called just before this).
        overlay_path = self.decisions_overlay_path
        if overlay_path:
            paths["decisions_overlay"] = overlay_path

        _detach.record_output_files(phase_dir, **paths)
        record_artifacts(
            path for path in paths.values() if path and os.path.exists(path)
        )

    def _write_item_counts(self, rows: List[Dict[str, Any]]) -> Dict[str, int]:
        """Count items by the scheduler's verdict, rather than dispatch success.

        An ``ok`` dispatch may be a no-op or a clean failure. Neither is
        evidence that its requested changes were applied. Counted over
        :meth:`_phase_rows`, the rows the report lists, so the count lines
        agree with the table under them.
        """
        counts = {
            "applied": 0, "no-op": 0, "clean-failure": 0,
            "declined": 0, "skipped": 0,
        }
        for row in rows:
            verdict = row.get("write_outcome")
            if self._row_ok(row) and verdict in counts:
                # Fix round 18: an item its batch declined, or one skipped at
                # the user's request, is never counted under the batch's
                # verdict (an `applied` batch did not apply it).
                declined, skipped = self._row_not_applied(row)
                counts[verdict] += len([
                    item for item in self._row_item_ids(row)
                    if item not in declined and item not in skipped
                ])
                counts["declined"] += len(declined)
                counts["skipped"] += len(skipped)
        return counts

    def _not_applied_lines(self, rows: List[Dict[str, Any]]) -> List[str]:
        """One plain line per item a finished batch did not apply on purpose
        (fix round 18): ``<title> [<id8>] (fix 2 of apply-fix-batch-1) not
        applied: the batch declined it — <reason>``, and the same for an item
        skipped at the user's request. Over the finished (``ok``) rows only:
        a stopped batch is dispatched again."""
        word = "fix" if self.write_kind == "apply_code_fixes" else "suggestion"
        lines: List[str] = []
        for row in rows:
            if not self._row_ok(row):
                continue
            declined, skipped = self._row_not_applied(row)
            if not declined and not skipped:
                continue
            item_ids = self._row_item_ids(row)
            titles = {
                member: str(item.get("title") or item.get("theme") or "").strip()
                for member, item in self._row_items_with_ids(row, item_ids)
                if member
            }
            for member in item_ids:
                # Fix round 26: the record keeps the reason's closing stop.
                # Fix round 28 (live run 12 #7): so does this line, which
                # ends with it; the notice's join (`join_clauses`) drops it
                # only where another clause follows (OpenCode decline's
                # notice lost it as its last clause).
                if member in declined:
                    why = f"the batch declined it — {str(declined[member] or '').strip()}"
                elif member in skipped:
                    why = f"skipped at your request — {str(skipped[member] or '').strip()}"
                else:
                    continue
                title = titles.get(member) or "Untitled"
                lines.append(
                    f"{title} [{member[:8]}] ({word} {item_ids.index(member) + 1} "
                    f"of {row.get('task_id')}) not applied: {why}"
                )
        return lines

    def print_write_outcome_summary(self) -> None:
        """Report what the batch loop DID, plus the decision summary.

        Two gaps close here. The first is tense: the log's 12 KB tail described
        batches that had already run, and carried no outcome, duration or runner
        anywhere in it. The second is reach: ``util decisions`` (step 3 of the
        apply instructions) is the only surface for the applied/skipped
        breakdown, and on the ``--exec-subagents`` leg the phase finishes in one
        invocation, so that step never runs — the per-item reasons, which are the
        good part, existed only inside ``orchestrator_output.json``.
        """

        result = self.write_result
        rows = self._phase_rows()
        ok = [row for row in rows if self._row_ok(row)]
        item_counts = self._write_item_counts(rows)
        target = self.target_file
        touched = self.touched_files()

        print(f"\n{'=' * 60}")
        print(f"{self.phase_name.upper()}: RESULT")
        print(f"{'=' * 60}")
        # F7: a phase with no single write target (has_single_write_target False —
        # apply-code-fixes partitions by file_key) used to fall back to
        # `self.plan_path` here, which the phase never opens, so every run named
        # the plan as what it changed. The files the batches actually verified
        # changed are the honest answer, and they exist for every phase.
        if target:
            print(f"File: {target}")
        else:
            print(f"Files changed: {', '.join(touched) if touched else '(none)'}")
        print(
            f"Batches: {len(ok)}/{len(rows)} ok"
            + self._rows_provenance_note(rows)
        )
        print(f"{self.item_noun_plural.capitalize()} applied: {item_counts['applied']}")
        if item_counts["declined"]:
            print(
                f"{self.item_noun_plural.capitalize()} declined by their batch "
                f"(not applied): {item_counts['declined']}"
            )
        if item_counts["skipped"]:
            print(
                f"{self.item_noun_plural.capitalize()} skipped at your request "
                f"(not applied): {item_counts['skipped']}"
            )
        if item_counts["no-op"]:
            print(f"{self.item_noun_plural.capitalize()} needing no changes: {item_counts['no-op']}")
        if item_counts["clean-failure"]:
            print(f"{self.item_noun_plural.capitalize()} without verified changes: {item_counts['clean-failure']}")
        print(f"Skipped: {len(self.formatted_skipped)}")
        if getattr(result, "stopped_at_batch", None) is not None:
            print(f"Stopped at batch: {result.stopped_at_batch}")
        failing = {
            str(row.get("task_id")): row_batch_check_findings(row)
            for row in rows
            if self._row_ok(row) and row_batch_check_findings(row)
        }
        if failing:
            # Fix round 14: applied, but not a clean finish.
            print(f"Not a clean finish: {batch_check_summary(failing)}")
        if getattr(result, "unverified", None):
            print(result.unverified)

        if rows:
            print("\nBatches:")
            for row in rows:
                count = len(self._row_item_ids(row))
                # `batch_reply.row_outcome_label`'s reading order.
                verdict = row.get("outcome_label") or row.get("write_outcome") or "-"
                if self._row_ok(row) and row_batch_check_findings(row):
                    verdict += (
                        ", its check could not run"
                        if batch_check_could_not_run(row_batch_check_findings(row))
                        else ", its check fails"
                    )
                print(
                    f"  {row.get('task_id')}{self._row_provenance(row)}: "
                    f"{row.get('status')} ({verdict}), "
                    f"{count} {self.item_noun}(s), "
                    f"{float(row.get('duration_seconds') or 0.0):.1f}s, "
                    f"runner {row.get('runner') or '(none)'}"
                )
                reason = row.get("reason")
                if reason:
                    print(f"      reason: {reason}")
            not_applied = self._not_applied_lines(rows)
            if not_applied:
                print(f"\n{self.item_noun_plural.capitalize()} not applied:")
                for line in not_applied:
                    print(f"  - {line}")

        for warning in self.consistency_warnings():
            print(f"\n[CONSISTENCY_WARNING] {warning}")

        # The decision summary, folded in: every skip with the status and the
        # specific reason validation gave it, plus its group id so the skip can
        # be looked up in the review report.
        if self.formatted_skipped:
            print(f"\nSkipped {self.item_noun_plural} (not applied):")
            for item in self.formatted_skipped:
                gid = str(item.get("group_id") or "")
                label = f" [{gid[:8]}]" if gid else ""
                print(
                    f"  - [{judge_status_label(item.get('status'))}] "
                    f"{item.get('title', 'Unknown')}{label}"
                )
                if item.get("reason"):
                    print(f"      reason: {item['reason']}")
        # What the judge decided, on the leg where nothing else reports it. The
        # instructions put a `## Decided by the judge agent` section in the summary
        # report, but that step lives on the native leg only, so before
        # this the one decision a `--yes --exec-subagents` run actually *made*
        # reached no output the phase wrote (measured 2026-09-16).
        decided = self.judge_decisions()
        if decided:
            print(f"\nDecided by the judge agent ({len(decided)}):")
            print(f"  judge: {', '.join(self._judges_of(decided))}")
            titles = self._titles_by_group_id()
            for group_id, record in decided.items():
                title = titles.get(group_id, group_id)
                context = record.get("batch_context") or {}
                print(
                    f"  - [{judge_outcome(record)}] {title} "
                    f"[{group_id[:8]}]"
                )
                print(f"      source: {judge_source_label(context.get('decision_source'))}")
                if record.get("reason"):
                    print(f"      reason: {record['reason']}")

        if self.formatted_human:
            print(f"\nStill needing a human ({len(self.formatted_human)}):")
            for item in self.formatted_human:
                print(f"  - {item.get('title', 'Unknown')}")

        for line in self._scope_summary_lines():
            print(line)

    def run_notes(self) -> List[str]:
        """The lines a host must relay beside this run's counts (fix round 14).

        Codex racing re-run 5, apply-task-suggestions: the log carried
        ``[CONSISTENCY_WARNING] T003 depends on T004, listed after it`` and
        "Skipped: 1" (a suggestion the judge skipped), while the result the
        host read said "10/10 items applied" and nothing else, so the host
        reported "Applied 10 of 10". One line per consistency warning, and one
        naming every item left unapplied with why, its title and group id —
        the RESULT block's own facts, in plain words.
        """
        notes = [
            f"consistency warning: {warning}" for warning in self.consistency_warnings()
        ]
        # Fix round 18: an item a batch declined (or one skipped at the
        # user's request) is named with its reason, never only counted.
        notes.extend(self._not_applied_lines(self._phase_rows()))
        skipped = list(self.formatted_skipped or [])
        if skipped:
            applied = self._write_item_counts(self._phase_rows())["applied"]
            noun = self.item_noun if len(skipped) == 1 else self.item_noun_plural
            by_label: Dict[str, List[str]] = {}
            for item in skipped:
                gid = str(item.get("group_id") or "")
                title = str(item.get("title") or "Unknown").strip()
                by_label.setdefault(judge_status_label(item.get("status")), []).append(
                    f"{title}{f' [{gid[:8]}]' if gid else ''}"
                )
            shown = "; ".join(
                f"{label}: {', '.join(titles[:5])}"
                + (f" (+{len(titles) - 5} more)" if len(titles) > 5 else "")
                for label, titles in by_label.items()
            )
            # Fix round 26 (live run 11, OpenCode 05: the host said the task
            # suggestions went "to plans/racing-game.md"): the file they went to.
            target = applied_to_label(self.target_file, self.plan_path)
            notes.append(
                f"{len(skipped)} {noun} not applied, beside the {applied} "
                f"applied{f' to {target}' if target else ''} — {shown} "
                "(reasons in summary.md)"
            )
        scope_note = _scope.deferral_note(self.scope_deferred, self.item_noun_plural)
        if scope_note:
            notes.append(scope_note)
        return notes

    def publish_run_notes(self) -> None:
        """Hand :meth:`run_notes` to the result line and to ``status``.

        The run's own ``notice`` (appended, never replacing one) for a
        foreground caller, and ``progress.notes`` in the phase's
        ``.status.json``, which a detached run's terminal poll carries into
        its ``notice`` — the poll is the only result line a tool route reads.
        """
        notes = self.run_notes()
        if not notes:
            return

        _run_record.report_progress(
            os.path.join(self.out_dir, self.phase_name), notes=notes,
        )
        _cli.add_notice(join_clauses(notes))

    def judge_decisions(self) -> Dict[str, Dict[str, Any]]:
        """This phase's recorded decisions that a judge subagent made.

        The same filter the instructions' ``## Decided by the judge agent`` section
        specifies: ``human_decisions_{phase}`` entries whose
        ``batch_context.decision_source`` is ``judge_auto_decide`` or
        ``judge_auto_decide_salvage`` (or the ``claude_*`` spelling of either
        that a run started before the rename recorded).
        """
        if self.state is None:
            return {}
        try:
            recorded = self.state.get_all_human_decisions(self.phase_name)
        except Exception:  # noqa: BLE001 - reporting must not fail a run
            return {}
        return {
            group_id: record
            for group_id, record in (recorded or {}).items()
            if is_judge_source(
                ((record or {}).get("batch_context") or {}).get("decision_source")
            )
        }

    @staticmethod
    def _judge_breakdown(decided: Dict[str, Dict[str, Any]]) -> str:
        """`` (N approved, N salvaged, N skipped)`` for the summary's count line.

        The same three counts the ingest line prints, so one run never reports
        a salvage as "salvaged" in one place and "approved" in another.
        """
        if not decided:
            return ""
        outcomes = [judge_outcome(record) for record in decided.values()]
        return (
            f" ({outcomes.count('approved')} approved, "
            f"{outcomes.count('salvaged')} salvaged, "
            f"{outcomes.count('skipped')} skipped)"
        )

    @staticmethod
    def _judges_of(decided: Dict[str, Dict[str, Any]]) -> List[str]:
        """The distinct judges named by *decided*'s records, in first-seen order."""
        judges: List[str] = []
        for record in decided.values():
            judge = str(((record or {}).get("batch_context") or {}).get("judge")
                        or "unrecorded")
            if judge not in judges:
                judges.append(judge)
        return judges

    def _titles_by_group_id(self) -> Dict[str, str]:
        """``group_id -> title`` over every work set, for decision reporting."""
        titles: Dict[str, str] = {}
        for formatted in (
            self.formatted_valid,
            self.formatted_human,
            self.formatted_skipped,
        ):
            for item in formatted or []:
                gid = str(item.get("group_id") or "")
                if gid:
                    titles[gid] = str(item.get("title") or gid)
        return titles

    @staticmethod
    def _batch_member_items(batch: Optional[Dict[str, Any]]) -> List[Dict[str, Any]]:
        """The formatted items a batch dict carries (F10).

        ``fixes`` for a ``CodeFixBatch``, ``suggestions`` for the two sibling
        phases' ``SuggestionBatch`` — whichever key the batch's own
        ``to_dict()`` used, so this reads all three phases' batches without a
        subclass override.
        """
        if not batch:
            return []
        return list(batch.get("fixes") or batch.get("suggestions") or [])

    @staticmethod
    def _read_batch_result_notes(
        output_path: Optional[str], item_ids: Optional[List[str]] = None
    ) -> Optional[str]:
        """Best-effort read of a write batch's own ``notes`` field (F10).

        ``notes`` (``schemas/write_batch_result.schema.json``) is the runner's
        free-text detail beyond the structured ``status``/``ids``/``summary``
        fields ``TaskOutcome`` already carries — on a real run, the only place a
        batch's own account of *why* (e.g. "Fix 1: car.accel 32->28 per plan
        §8.") survives past verification. Silent on any read/parse failure —
        the field is optional and this is reporting, never gating.

        With ``item_ids``, a file whose own ``ids`` name none of them is
        another batch's: an apply result file is named by position, and a
        resumed run may have rewritten it for the batch that now holds it.
        """
        if not output_path or not os.path.isfile(output_path):
            return None
        try:
            with open(output_path, "r", encoding="utf-8") as handle:
                data = json.load(handle)
        except (OSError, json.JSONDecodeError):
            return None
        if not isinstance(data, dict):
            return None
        returned = [str(i) for i in data.get("ids") or []]
        if item_ids and returned and not set(returned) & set(item_ids):
            return None
        notes = data.get("notes")
        return notes if isinstance(notes, str) and notes.strip() else None

    def _row_items(
        self, row: Dict[str, Any], item_ids: List[str]
    ) -> List[Dict[str, Any]]:
        """The formatted items (titles, files) a report row's batch carried.

        This run's batch of the same id when it holds the same items — task
        and batch are materialized from the same ``self.batches`` list, in the
        same order (``run_write_executor``), so a positional zip joins them —
        else the items found by member id: an earlier run's row whose
        positional id now names another batch.
        """
        return [item for _member, item in self._row_items_with_ids(row, item_ids)]

    def _row_items_with_ids(
        self, row: Dict[str, Any], item_ids: List[str]
    ) -> List[Tuple[Optional[str], Dict[str, Any]]]:
        """:meth:`_row_items` with each item's own id beside it (fix round 18:
        a declined item is named by its id on the row). ``None`` for an item
        whose id cannot be told."""
        task_id = str(row.get("task_id", ""))
        for task, batch in zip(self.write_tasks, self.batches):
            if str(task.get("task_id", "")) != task_id or not isinstance(batch, dict):
                continue
            task_ids = [str(i) for i in task.get("expected_ids") or []]
            if not row.get("expected_ids") or sorted(task_ids) == sorted(item_ids):
                members = self._batch_member_items(batch)
                return [
                    (task_ids[index] if index < len(task_ids) else None, item)
                    for index, item in enumerate(members)
                ]
            break
        by_id = self._items_by_member_id()
        return [(i, by_id[i]) for i in item_ids if i in by_id]

    @staticmethod
    def _row_not_applied(row: Dict[str, Any]) -> Tuple[Dict[str, str], Dict[str, str]]:
        """``(declined, skipped)``: a row's items its batch declined and the
        items a ``--human-task <id>=skip`` answer recorded as skipped at the
        user's request, each ``{id: reason}`` (fix round 18). Never applied."""

        return (
            row_declined(row),
            row_declined({"declined": row.get("skipped_items")}),
        )

    @staticmethod
    def _item_file_lines(item: Dict[str, Any]) -> List[str]:
        """An item's ``   - File: <path>[:<a>-<b>]`` line, when it names one."""
        file_path = item.get("file")
        if not file_path:
            return []
        line_range = item.get("line_range") or []
        if len(line_range) >= 2:
            return [f"   - File: {file_path}:{line_range[0]}-{line_range[1]}"]
        return [f"   - File: {file_path}"]

    def _not_applied_item_lines(
        self, member: str, item: Optional[Dict[str, Any]], task_id: str, why: str,
    ) -> List[str]:
        """One item of a not-applied section (fix round 22): ``- **<title>**
        (`<id>`, <batch>) — <reason>``, then its file; the id alone when this
        run's batches no longer hold the item."""
        if item is None:
            return [f"- `{member}` ({task_id}) — {why}"]
        title = item.get("title") or item.get("theme") or "Untitled"
        return [f"- **{title}** (`{member}`, {task_id}) — {why}"] + self._item_file_lines(item)

    def write_apply_summary_report(self) -> Optional[str]:
        """Write ``{phase}/summary.md`` — the report the instructions promise (F3).

        Their *Output Files* block lists this file for all three apply phases,
        and their *Generate Summary Report* step describes its sections; both
        live on the native leg, which ``--exec-subagents`` never reaches ("the phase
        finishes in that one invocation"). So the executor leg writes the same
        document itself, from the data it already has: the batch outcomes, the
        skip list rebuilt after judging, and the judge's own decisions.

        F10 extends it with the per-fix detail the instructions' own template
        promises and that was sitting unread on disk: each batch's own items
        (title, file:lines when the item has them, applied/not-applied) from
        ``self.batches``, the runner's free-text ``notes`` from its result file,
        plus ``Base ref`` / batching-efficiency lines when the orchestrator
        computed them (empty for the two sibling phases, which is why both are
        conditional rather than assumed present).

        Best-effort and never fatal — a report is not worth failing an applied
        run over. Returns the path written, or ``None``.
        """
        phase_dir = os.path.join(self.out_dir, self.phase_name)
        result = self.write_result
        # #28: the phase's rows, not this run's outcomes — a `--resume` keeps
        # the batches an interrupted run of this review cycle finished, marked
        # "(earlier run)" with that run's runner, duration and verdict. The
        # count lines below are computed from the same rows as the table.
        rows = self._phase_rows()
        ok = [row for row in rows if self._row_ok(row)]
        item_counts = self._write_item_counts(rows)
        decided = self.judge_decisions()
        titles = self._titles_by_group_id()
        nouns = self.item_noun_plural

        lines = [
            f"# Applied {nouns.title()} Report",
            "",
            # `**Commit brief**:` on a commit review (plans/review-commits.md §2.8).
            f"**{self.document_title()}**: {self.plan_path}",
        ]
        target = self.target_file
        touched = self.touched_files()
        if target:
            lines.append(f"**Applied to**: {target}")
        elif touched:
            # F7: apply-code-fixes has no single write target — the files the
            # batches verified changed is the honest "what did this phase
            # change" answer, where before nothing named it at all.
            lines.append(f"**Files changed**: {', '.join(touched)}")
        base_ref = self.resolve_base_ref()
        if base_ref:
            lines.append(f"**Base ref**: {base_ref}")
        lines += [
            f"**Generated**: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
            "",
            "## Summary",
            f"- Batches processed: {len(ok)}/{len(rows)}"
            + self._rows_provenance_note(rows),
            f"- {nouns.capitalize()} applied: {item_counts['applied']}",
            *(
                [f"- {nouns.capitalize()} declined by their batch (not "
                 f"applied): {item_counts['declined']}"]
                if item_counts["declined"] else []
            ),
            *(
                [f"- {nouns.capitalize()} skipped at your request (not "
                 f"applied): {item_counts['skipped']}"]
                if item_counts["skipped"] else []
            ),
            f"- {nouns.capitalize()} skipped: {len(self.formatted_skipped)}",
            f"- Decided by the judge agent: {len(decided)}"
            + self._judge_breakdown(decided),
        ]
        if item_counts["no-op"]:
            lines.append(f"- {nouns.capitalize()} needing no changes: {item_counts['no-op']}")
        if item_counts["clean-failure"]:
            lines.append(f"- {nouns.capitalize()} without verified changes: {item_counts['clean-failure']}")
        # F4: the instructions' own report template requires a verification line
        # and this leg had none, so a phase that applied seven code fixes without
        # running any check read exactly like one that had. Only for the
        # code-editing phase — a typecheck has nothing to say about a plan file.
        if self.write_kind in CODE_WRITE_KINDS:
            lines.append(f"- Verification: {verification_line(result)}")
        if self.batching_stats.get("batching_enabled"):
            lines.append(
                f"- Batching efficiency: "
                f"{self.batching_stats.get('subagent_calls_saved', 0)} "
                f"subagent call(s) saved "
                f"({self.batching_stats.get('efficiency_gain_percent', 0)}%)"
            )
        lines += [
            "",
            "## Applied Changes",
            "",
        ]
        # Fix round 22 (live run 9): an item its batch declined, or that a
        # `=skip` answer recorded as skipped at your request, is listed in a
        # section of its own below, never under this applied heading.
        not_applied_sections: Dict[str, List[str]] = {
            DECLINED_SECTION_HEADING: [], SKIPPED_SECTION_HEADING: [],
        }
        if rows:
            for row in rows:
                item_ids = self._row_item_ids(row)
                # `batch_reply.row_outcome_label`'s reading order.
                verdict = row.get("outcome_label") or row.get("write_outcome") or "-"
                failing = (
                    (", its check could not run"
                     if batch_check_could_not_run(row_batch_check_findings(row))
                     else ", its check fails")
                    if self._row_ok(row) and row_batch_check_findings(row) else ""
                )
                lines.append(
                    f"### {row.get('task_id')}{self._row_provenance(row)} — "
                    f"{row.get('status')} ({verdict}{failing})"
                )
                lines.append(
                    f"**{nouns.capitalize()}**: {len(item_ids)}  "
                    f"**Duration**: {float(row.get('duration_seconds') or 0.0):.1f}s  "
                    f"**Runner**: {row.get('runner') or '(none)'}"
                )
                members = self._row_items_with_ids(row, item_ids)
                items = [item for _member, item in members]
                declined, skipped = self._row_not_applied(row)
                if not items and item_ids and row.get("from_earlier_run"):
                    # An earlier batch whose items this run no longer selects:
                    # its ids are all that is left to name them by.
                    lines.append(
                        "**Items**: " + ", ".join(f"`{i}`" for i in item_ids)
                    )
                titles_by_member = {member: item for member, item in members}
                for kept, heading in (
                    (declined, DECLINED_SECTION_HEADING),
                    (skipped, SKIPPED_SECTION_HEADING),
                ):
                    for member, why in kept.items():
                        not_applied_sections[heading] += self._not_applied_item_lines(
                            member, titles_by_member.get(member),
                            str(row.get("task_id")), why,
                        )
                if declined or skipped:
                    told = [
                        f'{len(kept)} {words} (listed under "{heading}" below)'
                        for kept, words, heading in (
                            (declined, "declined by the batch", DECLINED_SECTION_HEADING),
                            (skipped, "skipped at your request", SKIPPED_SECTION_HEADING),
                        ) if kept
                    ]
                    lines.append(f"**Not applied**: {'; '.join(told)}")
                listed = [
                    (member, item) for member, item in members
                    if member not in declined and member not in skipped
                ]
                if listed:
                    item_status = {
                        "applied": "Applied",
                        "no-op": "No changes needed",
                        "clean-failure": "No verified changes",
                        "partial-application": "Partial application; inspect batch",
                    }.get(verdict, "Not applied")
                    for item_index, (member, item) in enumerate(listed, 1):
                        item_title = item.get("title") or item.get("theme") or "Untitled"
                        lines.append(f"{item_index}. **{item_title}** - {item_status}")
                        lines += self._item_file_lines(item)
                notes = self._read_batch_result_notes(
                    row.get("output_path"), item_ids
                )
                if notes:
                    lines.append(f"**Notes**: {notes}")
                reason = row.get("reason")
                if reason:
                    lines.append(f"**Reason**: {reason}")
                lines.append("")
            # Fix round 14: the batches whose own check failed, whole, in the
            # commit modes' words on a commit review (§2.8).
            section = batch_check_section(
                rows, commit_review=commit_view(self.plan_path) is not None)
            if section:
                lines += section[1:] + [""]
            for heading, entries in not_applied_sections.items():
                if entries:
                    lines += [f"## {heading}", ""] + entries + [""]
        else:
            lines += ["(no batches were dispatched)", ""]

        if decided:
            lines += [
                f"## Decided by the judge agent ({len(decided)})",
                "",
                f"judge: {', '.join(self._judges_of(decided))}",
                "",
                f"{nouns.capitalize()} whose decision was offloaded to a judge "
                f"subagent (`{AGENT_DECIDE_FLAG}`, or a per-item \"Let the agent "
                "decide\" selection).",
                "",
            ]
            for group_id, record in decided.items():
                context = record.get("batch_context") or {}
                lines.append(
                    f"### {titles.get(group_id, group_id)} "
                    f"({context.get('importance_at_decision', 'MEDIUM')}) — "
                    f"{judge_outcome(record).capitalize()}"
                )
                lines.append(f"**Group**: `{group_id}`")
                lines.append(f"**Source**: {judge_source_label(context.get('decision_source'))}")
                if context.get("salvaged_description"):
                    lines.append(f"**Kept**: {context['salvaged_description']}")
                if context.get("dropped"):
                    lines.append(f"**Dropped**: {context['dropped']}")
                if record.get("reason"):
                    lines.append(f"**Reason**: {record['reason']}")
                lines.append("")

        warnings = self.consistency_warnings()
        if warnings:
            lines += ["## Consistency warnings", ""]
            lines += [f"- {warning}" for warning in warnings]
            lines.append("")

        if self.formatted_skipped:
            lines += [f"## Skipped {nouns.title()}", ""]
            for item in self.formatted_skipped:
                lines.append(
                    f"### {item.get('title', 'Unknown')} "
                    f"[{judge_status_label(item.get('status'))}]"
                )
                gid = str(item.get("group_id") or "")
                if gid:
                    lines.append(f"**Group**: `{gid}`")
                if item.get("reason"):
                    lines.append(f"**Reason**: {item['reason']}")
                if item.get("files"):
                    # A commit guard skip (§2.7): the files that caused it.
                    lines.append(
                        "**Files**: " + ", ".join(f"`{f}`" for f in item["files"])
                    )
                lines.append("")

        # The scope policy's deferrals (plan §5): their own section, never
        # under a skipped or applied heading.
        lines += self._scope_summary_lines(markdown=True)

        path = os.path.join(phase_dir, "summary.md")
        try:
            os.makedirs(phase_dir, exist_ok=True)
            with open(path, "w", encoding="utf-8") as handle:
                handle.write("\n".join(lines).rstrip() + "\n")
        except OSError as exc:  # noqa: BLE001 - a report must not fail a run
            self.logger.warning("summary report not written: %s", exc)
            return None
        print(f"[write-subagents] summary report: {path}")
        return path

    def patch_write_batch_report_summary_file(self, summary_path: str) -> None:
        """Fill in ``write_batch_report.json``'s ``summary_file`` after the fact (F11).

        ``WriteBatchScheduler`` serializes that report inside
        ``run_write_executor()``, before this base ever calls
        ``write_apply_summary_report()`` — the scheduler only fills
        ``summary_file`` itself when constructed with its own ``summary_file``
        argument, which the apply phases never pass (they write their own
        summary here, on this leg). So the report on disk said
        ``summary_file: null`` for a run that went on to write one a few lines
        later. Patched here, once the apply phase's own path is known, rather
        than by changing the scheduler (owned elsewhere — see AGENTS.md).

        Best-effort: a read/parse/write failure is logged and never raised, the
        same posture as the report it patches.
        """
        if self.write_result is not None:
            self.write_result.summary_file = summary_path
        report_path = getattr(self.write_result, "report_path", None)
        if not report_path or not os.path.isfile(report_path):
            return
        try:
            with open(report_path, "r", encoding="utf-8") as handle:
                report = json.load(handle)
        except (OSError, json.JSONDecodeError) as exc:  # noqa: BLE001 - best-effort
            self.logger.warning("write_batch_report.json not patched: %s", exc)
            return
        if not isinstance(report, dict) or report.get("summary_file") == summary_path:
            return
        report["summary_file"] = summary_path
        try:
            failure_capture._atomic_write_json(report_path, report)
        except OSError as exc:  # noqa: BLE001 - best-effort
            self.logger.warning("write_batch_report.json not patched: %s", exc)

    def regenerate_decisions_overlay(self) -> Optional[str]:
        """Badge the review report's findings with this phase's decisions (F3).

        The in-process twin of ``util report regenerate-decisions --apply-phase
        {phase}``, which the instructions run on the native leg only.
        Called as a function rather than shelled out: the executor leg is
        already inside the process that holds the decisions, and a subprocess
        would re-resolve the skill dir it is running from.

        Best-effort by design — the command it mirrors exits 0 with a notice
        when the review predates the ``report_data.json`` sidecar.
        """
        if self.state is None:
            return None
        review_dir = Path(self.out_dir) / self.review_subdir
        if not (review_dir / "report_data.json").exists():
            return None
        decisions = self.state.get_all_human_decisions(self.phase_name)
        # The commit guard's skips badge their groups beside the decisions
        # (plans/review-commits.md §2.10): read from the saved guard.
        guard = None
        if self.pinned is not None:
            guard = guard_record(self.state.state)
        # A recorded scope-policy change (an apply override, its deferrals)
        # refreshes the report's eligibility even with no decision to badge.
        if (not decisions and not (guard and guard.get("skipped"))
                and not scope_regeneration_needed(review_dir, self.state.state)):
            return None
        try:
            report_path, matched = regenerate_report_with_human_decisions(
                review_dir, decisions, **({"guard": guard} if guard else {}),
                scope_state=self.state.state,
            )
        except Exception as exc:  # noqa: BLE001 - an overlay must not fail a run
            self.logger.warning("decision overlay not regenerated: %s", exc)
            return None
        if report_path is None:
            return None
        print(
            f"[write-subagents] decisions overlaid on {report_path} "
            f"({matched} of {len(decisions)} decision(s) matched)"
        )
        if matched < len(decisions):
            self.logger.warning(
                "decision overlay matched %d of %d decision(s) on %s — the "
                "rest joined no group (no groupHash, or a stale group id)",
                matched, len(decisions), report_path,
            )
        return str(report_path)


__all__ = ["ApplyPhaseReport", "applied_to_label"]
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: 321kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 321kUpdated 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: 321kUpdated 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: 321kUpdated Claude CodeCodexVerifiedInstall