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/commit_attribution.py

View on GitHub
"""Which commit introduced each finding of a commit review.

plans/review-commits.md §2.6, "Attribution is decided by Python, not trusted
from the model". A reviewer is asked for an ``introduced_by`` SHA, but a
model's answer is a reading, not a measurement: it can name a commit outside
the range, a side commit the block never lists, or the commit that wrote the
lines a drifted disk copy put at the cited numbers. So Python decides what it
can measure, and keeps the model's claim only as the checked fallback:

- **Blame, first parent only.** One ``git blame --porcelain --first-parent
  --root -L s,e … <base>..<head> -- <file>`` per file, one ``-L`` per group
  (git merges overlapping ranges). The group goes to the newest blamed
  commit that is in ``commit_range.commits``. ``--first-parent`` makes a line
  a merge brought in blame to that merge, which the block lists; the
  ``<base>..`` side bounds the walk, so an older line blames to the boundary,
  which is not in the list, and the cost follows the range rather than the
  file's age. A root range blames ``<head>`` alone, with ``--root`` keeping
  the root commit's lines attributable.
- **Blame that cannot run never fails the run.** A path absent at ``head``,
  a binary file (a NUL byte in its first 8000 bytes, git's own test), a
  ``line_range`` that starts past the last line (git refuses the whole call
  for one), and a call that fails or passes :data:`BLAME_TIMEOUT_S` each skip
  blame for the groups concerned, which fall back to the model's claim and
  then to ``none``, with one line naming the file and the reason. A range
  that only ends past the last line is clamped, as git does itself.
- **A drifted file's lines are checked first.** A reviewer that read a file
  from disk instead of at ``head`` reports the disk copy's numbers; blamed at
  ``head`` those name whichever commit wrote the lines that sit there, a
  confident wrong answer. So a group on a file in ``commit_range.drifted``,
  or one the shared change test (:func:`git_utils.paths_changed_since`, run
  once per pass) marks now, is blamed only when its ``anchor_text`` occurs at
  ``head`` within the clamped range (whitespace runs collapsed on both sides,
  so it may span lines). Otherwise its source is ``model-drifted``, or
  ``none`` when the claim is refused.
- **The model's claim.** A prefix of 7 or more hex digits matching exactly
  one entry of ``commits``; else a SHA that resolves strictly to a side
  commit of the range (``git rev-list <base>..<head>`` lists it, ``commits``
  does not), mapped to the merge that brought it onto the first-parent chain
  (the oldest entry of ``commits`` that ``git rev-list --ancestry-path
  <sha>..<head>`` lists, over all parents: a side commit that is no parent of
  any first-parent commit, the first of two on a side branch, still maps to
  its merge); anything else is refused.

The outcome is written as two sibling fields of each group,
``introduced_by`` (a full SHA or ``None``) and ``introduced_by_source``
(``blame``, ``model``, ``model-drifted`` or ``none``), never folded into its
title, description or theme, so neither enters the group hash
(``state_manager.generate_group_id``) and two models that disagree about the
commit still group together. Blame output lives in memory for one pass only.

Every git call goes through ``git_utils.git_argv`` (``tests/test_git_utils.py``
fails a runtime git list literal anywhere else).
"""

from __future__ import annotations

import re
import subprocess
from dataclasses import dataclass, field
from typing import Any, Dict, List, Mapping, Optional, Sequence, Set, Tuple

from .commit_range import RangeError, resolve_commit_strict
from .git_utils import git_argv, git_path, paths_changed_since, read_at_commit, run_git

#: One blame call (one file) may take this long before its groups fall back.
BLAME_TIMEOUT_S = 60

#: git's own binary test reads this many leading bytes for a NUL.
BINARY_SNIFF_BYTES = 8000

#: The shortest hex prefix a model's claim may use.
MIN_CLAIM_HEX = 7

#: The group fields this module writes.
INTRODUCED_BY = "introduced_by"
INTRODUCED_BY_SOURCE = "introduced_by_source"

SOURCE_BLAME = "blame"
SOURCE_MODEL = "model"
SOURCE_MODEL_DRIFTED = "model-drifted"
SOURCE_NONE = "none"
SOURCES: Tuple[str, ...] = (SOURCE_BLAME, SOURCE_MODEL, SOURCE_MODEL_DRIFTED, SOURCE_NONE)

#: The sources a report marks "(model)": the claim, not a measurement.
MODEL_SOURCES: Tuple[str, ...] = (SOURCE_MODEL, SOURCE_MODEL_DRIFTED)

_PORCELAIN_HEADER = re.compile(r"([0-9a-f]{40}|[0-9a-f]{64}) (\d+) (\d+)(?: (\d+))?")
_HEX_CLAIM = re.compile(r"[0-9a-f]{%d,64}" % MIN_CLAIM_HEX)
_FULL_SHA = re.compile(r"[0-9a-f]{40}|[0-9a-f]{64}")


@dataclass
class Outcome:
    """One group's attribution: the commit (full SHA or None) and its source."""

    sha: Optional[str]
    source: str


@dataclass
class AttributionPass:
    """What one pass decided, and what it found on the way.

    ``outcomes`` is per group, in the order the groups were given.
    ``drifted`` holds the (git-form) files of those groups the pass treated
    as drifted: the recorded ``commit_range.drifted`` ones plus those the
    change test marked now; the report's drift badges read it beside the
    record. ``blame_calls`` counts the blame calls made (one per file at most).
    ``skipped`` is ``(file, reason)`` for every file or group whose blame was
    skipped, as the run log names them.
    """

    outcomes: List[Outcome] = field(default_factory=list)
    drifted: Tuple[str, ...] = ()
    blame_calls: int = 0
    skipped: List[Tuple[str, str]] = field(default_factory=list)


@dataclass
class _Location:
    file: str
    start: int
    end: int
    anchor: str


# ---------------------------------------------------------------------------
# Reading the groups
# ---------------------------------------------------------------------------


def _members(group: Mapping[str, Any]) -> List[Mapping[str, Any]]:
    members = group.get("suggestions", group.get("issues", []))
    return [m for m in (members or []) if isinstance(m, Mapping)]


def _int(value: Any) -> Optional[int]:
    if isinstance(value, bool):
        return None
    if isinstance(value, int):
        return value
    if isinstance(value, str) and value.strip().isdigit():
        return int(value.strip())
    return None


def group_location(group: Mapping[str, Any]) -> Tuple[Optional[str], Optional[Tuple[int, int]], str]:
    """The group's ``(file, (start, end), anchor_text)``, read from its primary
    suggestion as apply-code-fixes reads it (``format_fix_for_output``), or
    from the group itself when it has no suggestions. ``start``/``end`` are
    ``None`` when the ``line_range`` is missing or unusable; a reversed range
    is put in order and a start below 1 is read as 1."""
    members = _members(group)
    source: Mapping[str, Any] = members[0] if members else group
    file = source.get("file")
    file = file.strip() if isinstance(file, str) and file.strip() else None
    anchor = source.get("anchor_text")
    anchor = anchor if isinstance(anchor, str) else ""
    raw = source.get("line_range")
    span: Optional[Tuple[int, int]] = None
    if isinstance(raw, (list, tuple)) and raw:
        start = _int(raw[0])
        end = _int(raw[1]) if len(raw) > 1 else start
        if start is not None and end is not None:
            start, end = max(1, min(start, end)), max(1, max(start, end))
            span = (start, end)
    return file, span, anchor


def _label(group: Mapping[str, Any], index: int) -> str:
    return str(group.get("display_label") or group.get("group_hash") or f"group {index + 1}")


# ---------------------------------------------------------------------------
# Git reads
# ---------------------------------------------------------------------------


def _line_count(data: bytes) -> int:
    """Lines as git counts them: newline-terminated ones plus an unterminated
    last line."""
    if not data:
        return 0
    return data.count(b"\n") + (0 if data.endswith(b"\n") else 1)


def _collapse(text: str) -> str:
    return " ".join(text.split())


def anchor_at_head(anchor: str, lines: Sequence[str], start: int, end: int) -> bool:
    """Whether *anchor* occurs in lines ``start..end`` (1-based, inclusive) of
    the file at ``head``, with runs of whitespace collapsed on both sides; it
    may span lines. An empty anchor never matches."""
    wanted = _collapse(anchor or "")
    if not wanted or start > end or start < 1:
        return False
    window = "\n".join(lines[start - 1:end])
    return wanted in _collapse(window)


def _run_blame(argv: List[str], cwd: Optional[str], timeout: float) -> subprocess.CompletedProcess:
    """The one spawn of a blame call (a seam for tests)."""
    where: Dict[str, str] = {"cwd": cwd} if cwd is not None else {}
    return subprocess.run(
        argv, capture_output=True, stdin=subprocess.DEVNULL, timeout=timeout, **where,
    )


def parse_porcelain(text: str) -> Dict[int, str]:
    """``{final line number: commit SHA}`` from ``git blame --porcelain``.

    Each blamed line is a header (``<sha> <orig> <final> [<count>]``), then
    key lines on a commit's first appearance, then the line's content behind a
    TAB; only headers are read, and only where a header is expected, so
    content and key text never pass for one."""
    blamed: Dict[int, str] = {}
    expecting_header = True
    for line in text.split("\n"):
        if expecting_header:
            match = _PORCELAIN_HEADER.fullmatch(line)
            if match:
                blamed[int(match.group(3))] = match.group(1)
                expecting_header = False
            continue
        if line.startswith("\t"):
            expecting_header = True
    return blamed


def _blame(file: str, spans: Sequence[Tuple[int, int]], base: Optional[str], head: str,
           cwd: Optional[str]) -> Tuple[Optional[Dict[int, str]], Optional[str]]:
    """Blame *spans* of *file* in one call: ``(lines, None)`` or ``(None, why)``."""
    args: List[str] = ["blame", "--porcelain", "--first-parent", "--root", "--no-textconv"]
    for start, end in spans:
        args += ["-L", f"{start},{end}"]
    args.append(f"{base}..{head}" if base is not None else head)
    args += ["--", file]
    try:
        proc = _run_blame(git_argv(*args, cwd=cwd), cwd, BLAME_TIMEOUT_S)
    except subprocess.TimeoutExpired:
        return None, f"git blame passed {BLAME_TIMEOUT_S}s"
    except (OSError, ValueError) as exc:
        return None, f"git blame could not run ({exc})"
    if proc.returncode != 0:
        stderr = (proc.stderr or b"").decode("utf-8", "replace").strip().splitlines()
        return None, f"git blame failed ({stderr[0] if stderr else f'exit {proc.returncode}'})"
    return parse_porcelain((proc.stdout or b"").decode("utf-8", "replace")), None


class _ClaimResolver:
    """The model's claim, checked against the range (§2.6). The side-commit
    list is read once per pass, and only when a claim needs it."""

    def __init__(self, commits: Sequence[str], base: Optional[str], head: str,
                 cwd: Optional[str]):
        self.commits = list(commits)
        self.commit_set = set(self.commits)
        self.base = base
        self.head = head
        self.cwd = cwd
        self._side: Optional[Set[str]] = None
        self._merges: Dict[str, Optional[str]] = {}

    def _side_commits(self) -> Set[str]:
        if self._side is None:
            spec = f"{self.base}..{self.head}" if self.base is not None else self.head
            stdout, _, rc = run_git("rev-list", spec, check=False, cwd=self.cwd)
            listed = set(stdout.split()) if rc == 0 else set()
            self._side = listed - self.commit_set
        return self._side

    def _merge_for(self, side: str) -> Optional[str]:
        """The merge that brought *side* onto the first-parent chain: the
        oldest entry of ``commits`` that has *side* as an ancestor.

        ``rev-list --ancestry-path <side>..<head>`` lists every commit that
        descends from *side* and reaches ``head``, over all parents. Along the
        first-parent chain that is a suffix (a commit reaching *side* is
        reached by every later one), so its oldest member in ``commits`` is
        the merge. ``--first-parent`` cannot be added: the walk would then
        leave *side* only through first parents, which reach the merge only
        when *side* is the merge's own second parent, and the older commit of
        a two-commit side branch would be refused. One call per distinct side
        commit a claim names, remembered for the pass."""
        if side not in self._merges:
            stdout, _, rc = run_git(
                "rev-list", "--ancestry-path", f"{side}..{self.head}",
                check=False, cwd=self.cwd,
            )
            descendants = set(stdout.split()) if rc == 0 else set()
            # `commits` is newest first, so the last one reached is the oldest.
            reached = [sha for sha in self.commits if sha in descendants]
            self._merges[side] = reached[-1] if reached else None
        return self._merges[side]

    def resolve(self, claim: Any) -> Optional[str]:
        """The range commit *claim* names, or None (refused)."""
        if not isinstance(claim, str):
            return None
        tokens = claim.strip().strip("`'\"").split()
        if not tokens:
            return None
        text = tokens[0].strip("`'\".,;:()").lower()
        if not _HEX_CLAIM.fullmatch(text):
            return None
        matches = [sha for sha in self.commits if sha.startswith(text)]
        if len(matches) == 1:
            return matches[0]
        if matches:
            return None  # ambiguous within the range
        try:
            full = resolve_commit_strict(text, cwd=self.cwd or ".")
        except RangeError:
            return None
        if full not in self._side_commits():
            return None  # base, an older commit, or nothing in this range
        return self._merge_for(full)


def _claims(group: Mapping[str, Any]) -> List[Any]:
    """The members' own ``introduced_by`` values, primary first. The group's
    ``introduced_by`` is this module's output, never a claim."""
    return [m.get(INTRODUCED_BY) for m in _members(group) if m.get(INTRODUCED_BY)]


def _log(message: str) -> None:
    print(f"Attribution: {message}")


# ---------------------------------------------------------------------------
# The pass
# ---------------------------------------------------------------------------


def attribute_groups(groups: Sequence[Dict[str, Any]], record: Mapping[str, Any], *,
                     cwd: Optional[str]) -> AttributionPass:
    """Attribute every group to one commit of ``record["commits"]`` or to none,
    writing ``introduced_by`` and ``introduced_by_source`` onto each group.

    *record* is ``state.json``'s ``commit_range``; *cwd* is the repository
    root (the change test needs it). Never raises for a git failure: every
    case that cannot be measured falls back as §2.6 says."""
    commits = [str(entry.get("sha")) for entry in (record.get("commits") or ())
               if isinstance(entry, Mapping) and isinstance(entry.get("sha"), str)
               and _FULL_SHA.fullmatch(str(entry.get("sha")))]
    order = {sha: index for index, sha in enumerate(commits)}   # 0 = newest
    base_value = record.get("base")
    base = str(base_value) if base_value is not None else None
    head = str(record.get("head") or "")
    resolver = _ClaimResolver(commits, base, head, cwd)
    result = AttributionPass()

    locations: Dict[int, _Location] = {}
    by_file: Dict[str, List[int]] = {}
    for index, group in enumerate(groups):
        file, span, anchor = group_location(group)
        if file is None or span is None:
            continue
        name = git_path(file, cwd=cwd)
        locations[index] = _Location(name, span[0], span[1], anchor)
        by_file.setdefault(name, []).append(index)

    recorded = {git_path(path, cwd=cwd) for path in (record.get("drifted") or ())
                if isinstance(path, str) and path}
    files = list(by_file)
    drifted: Set[str] = {name for name in files if name in recorded}
    if files and head:
        drifted |= paths_changed_since(head, files, cwd=cwd)
    result.drifted = tuple(sorted(drifted))

    blamed: Dict[int, str] = {}
    drift_failed: Set[int] = set()
    for name, indexes in by_file.items():
        is_drifted = name in drifted
        data = read_at_commit(head, name, cwd=cwd) if head else None
        if data is None:
            reason = f"absent at {head[:7] or 'head'}"
            _log(f"blame skipped for {name} ({reason}); {len(indexes)} group(s) fall back "
                 f"to the model's claim")
            result.skipped.append((name, reason))
            if is_drifted:
                drift_failed.update(indexes)
            continue
        if b"\0" in data[:BINARY_SNIFF_BYTES]:
            _log(f"blame skipped for {name} (binary file); {len(indexes)} group(s) fall back "
                 f"to the model's claim")
            result.skipped.append((name, "binary file"))
            continue
        total = _line_count(data)
        lines = data.decode("utf-8", "replace").split("\n")
        spans: List[Tuple[int, int, int]] = []
        for index in indexes:
            loc = locations[index]
            end = min(loc.end, total)
            if is_drifted and not anchor_at_head(loc.anchor, lines, loc.start, end):
                why = ("no anchor_text" if not _collapse(loc.anchor)
                       else f"anchor_text not at lines {loc.start}-{loc.end} at {head[:7]}")
                _log(f"{name}: {_label(groups[index], index)} not blamed (file changed on disk "
                     f"since {head[:7]}; {why}); the model's claim is recorded as model-drifted")
                result.skipped.append((name, why))
                drift_failed.add(index)
                continue
            if loc.start > total:
                why = f"line_range starts at {loc.start}, past the last line ({total})"
                _log(f"blame skipped for {name}: {_label(groups[index], index)} ({why}); it "
                     f"falls back to the model's claim")
                result.skipped.append((name, why))
                continue
            spans.append((index, loc.start, end))
        if not spans:
            continue
        result.blame_calls += 1
        blame, why = _blame(name, [(s, e) for _, s, e in spans], base, head, cwd)
        if blame is None:
            _log(f"blame skipped for {name} ({why}); {len(spans)} group(s) fall back to the "
                 f"model's claim")
            result.skipped.append((name, why or "git blame failed"))
            continue
        for index, start, end in spans:
            found = [blame[line] for line in range(start, end + 1)
                     if blame.get(line) in order]
            if found:
                blamed[index] = min(found, key=lambda sha: order[sha])

    for index, group in enumerate(groups):
        if index in blamed:
            outcome = Outcome(blamed[index], SOURCE_BLAME)
        else:
            claim = next((sha for sha in (resolver.resolve(c) for c in _claims(group)) if sha),
                         None)
            if claim is None:
                outcome = Outcome(None, SOURCE_NONE)
            elif index in drift_failed:
                outcome = Outcome(claim, SOURCE_MODEL_DRIFTED)
            else:
                outcome = Outcome(claim, SOURCE_MODEL)
        group[INTRODUCED_BY] = outcome.sha
        group[INTRODUCED_BY_SOURCE] = outcome.source
        result.outcomes.append(outcome)
    return result


def attribute_review_groups(groups: Optional[Sequence[Dict[str, Any]]], state: Any, *,
                            repo_root: Optional[str]) -> Optional[AttributionPass]:
    """The call site's entry: attribute *groups* when the run's state records
    ``commit_range`` (a commit brief's review), else do nothing and return
    None. *state* is a ``StateManager`` or a ``state.json`` mapping."""
    getter = getattr(state, "get", None)
    record = getter("commit_range") if getter is not None else None
    if not isinstance(record, Mapping):
        return None
    group_list = [g for g in (groups or []) if isinstance(g, dict)]
    try:
        result = attribute_groups(group_list, record, cwd=repo_root)
    except Exception as exc:  # noqa: BLE001 - attribution never fails the run (§2.6)
        _log(f"skipped ({type(exc).__name__}: {exc}); every group is left unattributed")
        result = AttributionPass()
        for group in group_list:
            group[INTRODUCED_BY], group[INTRODUCED_BY_SOURCE] = None, SOURCE_NONE
            result.outcomes.append(Outcome(None, SOURCE_NONE))
        return result
    counts: Dict[str, int] = {}
    for outcome in result.outcomes:
        counts[outcome.source] = counts.get(outcome.source, 0) + 1
    if result.outcomes:
        summary = ", ".join(f"{counts[s]} {s}" for s in SOURCES if counts.get(s))
        _log(f"{len(result.outcomes)} group(s) attributed: {summary}")
    return result


def commits_by_sha(record: Optional[Mapping[str, Any]]) -> Dict[str, Mapping[str, Any]]:
    """``{sha: commits[] entry}`` from a ``commit_range`` record: the subjects a
    report renders come from here, with no git call (§2.6 "Rendering")."""
    table: Dict[str, Mapping[str, Any]] = {}
    for entry in (record or {}).get("commits") or ():
        if isinstance(entry, Mapping) and isinstance(entry.get("sha"), str):
            table[entry["sha"]] = entry
    return table
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