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

View on GitHub
"""How a write dispatch's reply is read: its check, its own batch check,
the items it declined, and the labels its outcome is recorded under.

No I/O: every function takes the parsed reply (or a recorded row) and
returns words. A check task's ``check`` object (:func:`read_check_reply`,
:func:`check_findings_from`), a code batch's own check and what it ran
(:func:`batch_check_findings`, :func:`ran_check_outcomes`,
:func:`ran_no_check`), the items a reply declined
(:func:`declined_items`), the ``WRITE_*`` outcome words and their labels
(:func:`write_outcome_label`), and the ``row_*`` readers of a recorded
row (``batch_ledger``, ``apply_report``, the scheduler). The executor,
the scheduler and ``util batch-done`` read the same reply through these,
so the two legs cannot read it differently. It imports none of the
executor's other modules; ``CHECK_FAILED_WITHOUT_FINDINGS`` lives in
``known_checks``, which imports nothing from here.

``utils.subagent_executor`` re-exports every name defined here for reading
only: patch one here, never through the executor
(docs/development/delegation.md#where-the-executors-helpers-live).
"""

from __future__ import annotations

import copy
from dataclasses import dataclass, field
from typing import Any, Dict, List, NamedTuple, Optional, Sequence

from .text_clip import clip
from . import known_checks as _known_checks


#: The four D3g write outcomes, plus the D3l containment failure. Recorded on the
#: outcome as its own axis rather than being folded into ``status``. "Applied"
#: and "no-op" are dispatches the loop continues past; "clean failure" (nothing
#: moved and the work is not done: a ``failed`` claim, a crash, or — an ``applied``
#: claim no byte backs, after its one re-send) is
#: never ``ok``, and "partial application" and "policy violation" stop it too.
WRITE_APPLIED = "applied"
WRITE_CLEAN_FAILURE = "clean-failure"
#: The runner said ``no-op`` and the byte comparison agrees. Its own outcome
#: rather than a clean failure, because the claim and the verdict AGREE: a
#: clean failure is *success* claimed with nothing moved, and labelling an
#: honest "already present" batch ``(batch failed — …)`` in the prior-changes
#: log and the summary table told the next batch, and the reader, that the
#: work had failed. Measured 2026-09-16 on two verification-only tasks.
WRITE_NO_OP = "no-op"
#: What a verification-only ``implement`` task (one declaring no files) reads as
#: when nothing moved: the check ran and left the repository as it was. A
#: *label*, never a ``write_outcome`` value — the outcome stays ``no-op``, which
#: resume, ``util restore-batch`` and every older reader key on — so it rides
#: beside it as ``outcome_label``. A verification-only task that moved bytes reads
#: ``partial-application`` like any other partial, so the pair is VERIFIED or
#: PARTIAL on every surface.
WRITE_LABEL_VERIFIED = "verified"
#: A verification-only task whose check ran, changed nothing and reported
#: problems in its reply's structured ``check`` object (``passed: false`` or a
#: non-empty ``findings`` list). Never ``verified``: racing re-run 4
#:  recorded T007 VERIFIED while ``npx html-validate`` had reported
#: two problems that lived only in the runner's free-text notes. Not a stop
#: either: what a check finds is a finding, never an exit code (AGENTS.md), and
#: review-code / apply-code-fixes are the phases that fix it — so the tasks
#: that do not depend on the check go on, ``write_outcome`` stays ``no-op``
#: and every surface names the findings. The tasks that DO depend on it are
#: not run: ``WriteBatchScheduler`` records them ``not run —
#: upstream check … reported problems`` and implement ends needing a human.
WRITE_LABEL_CHECK_FINDINGS = "check-findings"
WRITE_PARTIAL = "partial-application"

#: Bounds on what one check reply's ``findings`` may put on the surfaces
#: (summary.md, the reports, state.json, review-code's prompts).
CHECK_FINDINGS_MAX = 20
CHECK_FINDING_MAX_CHARS = 300

#: The finding recorded for a ``check`` that says neither that it passed nor
#: what it found (``{}``, ``{"passed": null, "findings": []}``): an unknown
#: result is never a pass.
CHECK_RESULT_UNKNOWN = (
    "the check's reply did not say whether it passed (its `check` object had "
    "no usable `passed` value and no findings); see the runner notes"
)

#: The words ``check.passed`` (and ``check.could_not_run``) may be spelled
#: in, besides the JSON booleans (a near-miss reply: ``"false"``, ``0``, and
#: since the strings ``"1"``/``"0"``, which read as the numbers
#: do). Anything else is an unknown result.
_CHECK_PASSED_WORDS = frozenset({"true", "yes", "pass", "passed", "1"})
_CHECK_FAILED_WORDS = frozenset({"false", "no", "fail", "failed", "0"})

#: A bare ``findings`` value that says "nothing found" (any case, a trailing
#: ``.``/``!`` ignored), read as ``[]`` only beside a ``passed`` that reads
#: true (``{"passed": true, "findings": "none"}`` was one
#: finding, "none", which held back every task after the check). Kept
#: short on purpose: any other text is a finding.
_EMPTY_FINDINGS_WORDS = frozenset({
    "", "none", "n/a", "na", "no problems", "no problems found", "no findings", "0",
})


def _says_nothing_found(value: Any) -> bool:
    """Whether a bare (non-list) ``findings`` value is an empty-ish marker."""
    if isinstance(value, bool):
        return False
    if isinstance(value, (int, float)):
        return value == 0
    if isinstance(value, str):
        word = " ".join(value.strip().lower().rstrip(".!").split())
        return word in _EMPTY_FINDINGS_WORDS
    return False


def write_outcome_label(
    write_outcome: Optional[str], verification_only: bool = False,
    check_findings: Optional[Sequence[str]] = None,
) -> Optional[str]:
    """The word every report shows for a write outcome (:data:`WRITE_LABEL_VERIFIED`)."""
    if verification_only and write_outcome == WRITE_NO_OP:
        return WRITE_LABEL_CHECK_FINDINGS if check_findings else WRITE_LABEL_VERIFIED
    return write_outcome


def _check_passed(value: Any) -> Optional[bool]:
    """``check.passed`` read leniently: ``True``/``False``, else ``None``.

    The JSON booleans, ``1``/``0`` (numbers or strings) and the words in
    :data:`_CHECK_PASSED_WORDS` / :data:`_CHECK_FAILED_WORDS` (any case);
    anything else (``null``, a missing key, ``"maybe"``) is unknown.
    """
    if isinstance(value, bool):
        return value
    if isinstance(value, (int, float)) and value in (0, 1):
        return bool(value)
    if isinstance(value, str):
        word = value.strip().lower()
        if word in _CHECK_PASSED_WORDS:
            return True
        if word in _CHECK_FAILED_WORDS:
            return False
    return None


def _finding_text(item: Any) -> str:
    """One finding as one line: an object is read as its non-empty values."""
    if item is None:
        return ""
    if isinstance(item, dict):
        # An object per finding (`{"command": …, "message": …}`) is read as
        # its values, so a near-miss shape still names the problem.
        item = "; ".join(
            f"{key}: {value}" for key, value in item.items()
            if value not in (None, "", [], {})
        )
    return " ".join(str(item).split())


class CheckReply(NamedTuple):
    """What a check task's reply says in its ``check`` object.

    ``findings`` is :func:`check_findings_from`'s answer. ``listed`` is
    whether the reply listed at least one finding of its own (not one this
    reader supplied: :data:`CHECK_FAILED_WITHOUT_FINDINGS`,
    :data:`CHECK_RESULT_UNKNOWN`). ``could_not_run`` is ``check.could_not_run``
    read as leniently as ``passed`` (``true``, ``1``, ``"1"``,
    ``"true"``/``"yes"``; :func:`_check_passed`): the runner says
    a check could not run.
    """

    findings: Optional[List[str]]
    listed: bool
    could_not_run: bool


def read_check_reply(result: Any) -> CheckReply:
    """The reply's ``check`` object, read (:class:`CheckReply`).

 (a coordinator decision after racing run 3: real runners
    answer ``failed`` for a check that ran and found problems): a check
    that could not run says so with ``check.could_not_run: true``, and only
    that, or a crash, is a check that did not run. ``write_verdict.decide``
    reads a ``failed`` reply whose ``check`` lists findings, and does not
    say it could not run, as findings.
    """
    findings = check_findings_from(result)
    check = result.get("check") if isinstance(result, dict) else None
    if not isinstance(check, dict):
        return CheckReply(findings, False, False)
    could_not_run = _check_passed(check.get("could_not_run")) is True
    listed = bool(findings) and findings[0] not in (
        _known_checks.CHECK_FAILED_WITHOUT_FINDINGS, CHECK_RESULT_UNKNOWN,
    )
    return CheckReply(findings, listed, could_not_run)


def check_findings_from(result: Any) -> Optional[List[str]]:
    """The structured check result of a write reply, as a findings list.

    ``None`` when the reply carries no ``check`` key at all (an older reply,
    a task that is not a check); ``[]`` when it says the check passed and
    lists nothing; otherwise the findings, one line each
    and bounded (:data:`CHECK_FINDINGS_MAX`, :data:`CHECK_FINDING_MAX_CHARS`).
    Read from the reply's own field, never from its notes.

    Lenient on shape, strict on meaning. The schema admits
    any ``check``, because a near-miss shape (``passed: "false"``,
    ``findings: "one problem"``, a number as a finding) used to be a
    ``schema_invalid`` reply, and implement had no report re-ask then, so the
    run stopped for good on a check that had answered (it has one; the lenient reading
    stays, so a near-miss costs no re-ask).
    Each shape is read here
    instead, and only a clear pass with nothing listed is a pass: a finding
    beside ``passed: true`` still counts, ``passed: false`` with none listed
    gets :data:`CHECK_FAILED_WITHOUT_FINDINGS`, and a ``check`` that says
    neither (``{}``, ``passed: null``, ``check: null``, a ``check`` that is
    not an object) gets :data:`CHECK_RESULT_UNKNOWN` — never a pass. ``check: null``
    read as no result, so a check task's reply
    carrying it was VERIFIED; only a missing key is no result now. A bare
    ``findings`` that says "nothing found" (``"none"``, ``"N/A"``, ``"No
    problems found."``, ``0``) beside a ``passed`` that reads true is
    ``[]`` (:data:`_EMPTY_FINDINGS_WORDS`).
    """
    if not isinstance(result, dict) or "check" not in result:
        return None
    check = result.get("check")
    if check is None:
        return [f"{CHECK_RESULT_UNKNOWN} (its `check` was null)"]
    if not isinstance(check, dict):
        shown = clip(check, 80)
        return [
            f"{CHECK_RESULT_UNKNOWN} (its `check` was "
            f"{type(check).__name__} {shown!r}, not an object)"
        ]
    raw = check.get("findings")
    passed = _check_passed(check.get("passed"))
    if isinstance(raw, list):
        items = raw
    elif raw is None:
        items = []
    elif passed is True and _says_nothing_found(raw):
        # "findings": "none" beside a pass says there is none.
        items = []
    else:
        # One finding given bare (a string, an object, a number).
        items = [raw]
    findings = []
    for item in items:
        text = _finding_text(item)
        if text:
            findings.append(clip(text, CHECK_FINDING_MAX_CHARS))
    if len(findings) > CHECK_FINDINGS_MAX:
        extra = len(findings) - (CHECK_FINDINGS_MAX - 1)
        findings = findings[:CHECK_FINDINGS_MAX - 1] + [
            f"(+{extra} more finding(s) in the batch result file)"
        ]
    if findings:
        return findings
    if passed is True:
        return []
    if passed is False:
        return [_known_checks.CHECK_FAILED_WITHOUT_FINDINGS]
    return [CHECK_RESULT_UNKNOWN]


#: The finding a code batch's own check carries when its reply said
#: ``check.could_not_run``: every surface then says "its check
#: could not run", never that it fails.
BATCH_CHECK_COULD_NOT_RUN = "its check could not run"


def batch_check_could_not_run(findings: Optional[Sequence[str]]) -> bool:
    """Whether a code batch's own-check findings say the check could not run."""
    return bool(findings) and str(findings[0]).startswith(BATCH_CHECK_COULD_NOT_RUN)


def batch_check_words(findings: Optional[Sequence[str]]) -> str:
    """How a surface names a code batch's own check that did not pass:
    "its check could not run", else "a check it ran fails"."""
    return (
        BATCH_CHECK_COULD_NOT_RUN if batch_check_could_not_run(findings)
        else "a check it ran fails"
    )


def batch_check_findings(result: Any) -> Optional[List[str]]:
    """What a code-writing batch's own ``check`` object says about the checks
    it ran on its edits.

    ``None`` when the reply reports no usable check — no ``check`` key, one
    that says neither whether it passed nor what failed (``{}``, ``null``), or
     one whose ``ran`` is empty, the contract's way of saying no
    check ran (:func:`ran_no_check`), and that names no finding and does not
    say it failed: saying nothing is not a finding here, as
    it is for a check task, whose whole answer it is. A command ``ran`` maps
    to ``failed`` is a failing check whatever ``passed`` says
    (:func:`ran_check_outcomes`). ``[]`` for a clear pass; else the failing checks, bounded. Codex
    racing run 5: an apply-code-fixes batch wrote "the bundled
    test fails" in its free-text ``notes``, the repository's test failed
    afterwards, and the run reported every fix applied. Never read from
    ``notes``.

    Not the check task's fail-closed reading: a check task's ``check`` is its whole
    verdict, so a finding beside
    ``passed: true`` counts there; here ``passed: true`` is the batch's own
    word that its checks passed, and what it lists beside it ("npm test: 12
    passed") is informational, never a failing check. ``could_not_run``
    (read as leniently as ``passed``) is one finding,
    :data:`BATCH_CHECK_COULD_NOT_RUN` with whatever the reply listed after
    it, so it reads "its check could not run", never "fails".

    One rule on both legs, the one
    ``references/own-check.md`` states for the native host's ``util
    batch-done --own-check``, first match wins: no ``check`` object is no
    check; ``could_not_run`` is that; a reply that ran nothing
    (:func:`ran_no_check`) is failing when it names a finding, whatever
    ``passed`` says (a pass of nothing is no verdict), or says ``passed:
    false`` (:data:`CHECK_FAILED_WITHOUT_FINDINGS` kept), and no check
    otherwise (a ``not_run`` reason with no ``ran`` ran nothing too); any other reply is
    a pass on ``passed: true``, failing on ``passed:
    false`` or a finding, a pass when only ``ran`` says what passed, and no
    check when it says nothing at all.
    """
    check = result.get("check") if isinstance(result, dict) else None
    if not isinstance(check, dict):
        # No `check` key, `null`, or not an object: no usable report.
        return None
    stated = _stated_findings(check)
    if _check_passed(check.get("could_not_run")) is True:
        text = BATCH_CHECK_COULD_NOT_RUN + (
            f": {'; '.join(stated)}" if stated else ""
        )
        return [clip(text, CHECK_FINDING_MAX_CHARS)]
    passed = _check_passed(check.get("passed"))
    if ran_no_check(result):
        # It ran nothing (an empty `ran`, every entry "not run", or only the
        # result shape's placeholder): its `passed: true` is a pass of
        # nothing, so a failure it names counts and nothing else is a pass;
        # a `passed: false` is a failing check (round 26 made
        # it "no check", where it had been CHECK_FAILED_WITHOUT_FINDINGS).
        if stated:
            return stated
        return [_known_checks.CHECK_FAILED_WITHOUT_FINDINGS] if passed is False else None
    ran = ran_check_outcomes(result)
    if passed is True:
        # What it lists beside a pass is informational.
        return _with_ran_failures([], ran)
    if passed is False:
        return _with_ran_failures(stated or [_known_checks.CHECK_FAILED_WITHOUT_FINDINGS], ran)
    if stated:
        return _with_ran_failures(stated, ran)
    # It says neither: `ran` alone says how its checks ended, if anything.
    if any(word == _ran_word("failed") for word in ran.values()):
        return _with_ran_failures([], ran)
    if any(word == _ran_word("passed") for word in ran.values()):
        return []
    return None


#: How much of a code batch's ``check.note`` the records carry.
CHECK_NOTE_MAX_CHARS = 300


def batch_check_note(result: Any) -> Optional[str]:
    """A code batch's ``check.note``: its own words about the checks it ran,
    one plain line bounded at :data:`CHECK_NOTE_MAX_CHARS`, or ``None``.

    T007 re-ran the check the user accepted and wrote its comment into the
    finding ("… (known problem the user accepted in T002)", "… — the
    accepted T002 problem (…), not caused by this note"), and the strict
    match read the finding as T007's own failure. The contract asks for
    each finding as the check reported it and for any comment here instead
    (:data:`batch_prompt.WRITE_CHECK_CONTRACT`). Recorded and shown
    beside the check on both legs (``util batch-done --note``); never read
    as a finding and never matched on."""
    check = result.get("check") if isinstance(result, dict) else None
    if not isinstance(check, dict):
        return None
    note = check.get("note")
    if not isinstance(note, str):
        return None
    return clip(note, CHECK_NOTE_MAX_CHARS) or None


def _ran_word(which: str) -> str:
    """``known_checks``' ``passed`` / ``failed`` outcome word."""
    return _known_checks.LISTED_FAILED if which == "failed" else _known_checks.LISTED_PASSED


def _stated_findings(check: Dict[str, Any]) -> List[str]:
    """The findings a ``check`` object names itself, bounded, without the
    placeholders :func:`check_findings_from` puts in for none. Beside a
    ``passed`` that reads true, an entry that only says nothing was found
    (``"none"``, ``"n/a"``, ``0``) is no finding either; beside any other ``passed`` it
    stays one, as before."""
    raw = check.get("findings")
    if _check_passed(check.get("passed")) is True:
        if isinstance(raw, list):
            raw = [item for item in raw if not _says_nothing_found(item)]
        elif _says_nothing_found(raw):
            raw = None
    return [
        text for text in (check_findings_from(
            {"check": {"passed": False, "findings": raw}}
        ) or [])
        if text not in (_known_checks.CHECK_FAILED_WITHOUT_FINDINGS, CHECK_RESULT_UNKNOWN)
    ]


def ran_check_outcomes(result: Any) -> Dict[str, str]:
    """``{command: passed|failed|not run}`` from a code batch's ``check.ran``
    The commands it says it ran, read as leniently as an
    apply-code-fixes batch's ``listed`` (``known_checks.listed_check_outcomes``).

    The contract asks for a map; a list of ``"<command>: <outcome>"`` strings
    is read too. An entry that cannot be read is left out, never guessed.
    """
    check = result.get("check") if isinstance(result, dict) else None
    ran = check.get("ran") if isinstance(check, dict) else None
    if isinstance(ran, list):
        pairs: Dict[str, Any] = {}
        for item in ran:
            if isinstance(item, str):
                command, sep, word = item.rpartition(":")
                if sep and command.strip():
                    pairs[command] = word
            elif isinstance(item, dict):
                # `{"command": …, "outcome": …}` per check, a near miss.
                command = next((item[k] for k in _RAN_COMMAND_KEYS if k in item), None)
                word = next((item[k] for k in _RAN_OUTCOME_KEYS if k in item), None)
                if isinstance(command, str) and command.strip():
                    pairs[command] = word
        ran = pairs
    if not isinstance(ran, dict) or not ran:
        return {}
    return {
        command: word for command, word in _known_checks.listed_check_outcomes(ran).items()
        if not _is_placeholder(command)
    }


#: The keys a ``ran`` entry written as an object names its command and its
#: outcome under, first found wins.
_RAN_COMMAND_KEYS = ("command", "cmd", "check", "name")
_RAN_OUTCOME_KEYS = ("outcome", "result", "status", "passed")


def _is_placeholder(command: str) -> bool:
    """Whether a ``ran`` key is the contract's own placeholder copied as it
    is (``<each check command you ran>``): it names no command."""
    text = command.strip()
    return len(text) > 1 and text[0] == "<" and text[-1] == ">"


def _names_a_command(entry: Any) -> bool:
    """Whether one entry of a ``ran`` list may name a command it ran: not the
    contract's placeholder, whether written as a ``"<command>: <outcome>"``
    string or (it read as a clean pass) as
    an object whose command is the placeholder. An entry that cannot be read
    counts, so what ran stays unknown rather than nothing."""
    if isinstance(entry, str):
        return not _is_placeholder(entry.rpartition(":")[0] or entry)
    if isinstance(entry, dict):
        command = next((entry[k] for k in _RAN_COMMAND_KEYS if k in entry), None)
        return not (isinstance(command, str) and _is_placeholder(command))
    return True


def ran_no_check(result: Any) -> bool:
    """Whether a code batch's ``check`` says it ran no check:
    its ``ran`` is present and empty, holds only the contract's placeholder,
    or every entry in it reads ``not run`` — or it has no
    ``ran`` at all but gives a ``not_run`` reason, the contract's other half
    of "I ran no check", so ``{"passed": true, "not_run": "…"}`` is never a
    pass of nothing.

    A missing ``ran`` with no ``not_run`` reason is not this (an older reply,
    read as before), and neither is a ``ran`` holding an entry that cannot be
    read: what it ran is then unknown, and ``passed``/``findings`` decide.
    """
    check = result.get("check") if isinstance(result, dict) else None
    ran = check.get("ran") if isinstance(check, dict) else None
    if ran is None and isinstance(check, dict):
        reason = check.get("not_run")
        return isinstance(reason, str) and bool(reason.strip())
    if not isinstance(ran, (dict, list)):
        return False
    # The contract's placeholder copied as it is names no command (a reply
    # that pasted the shape without running anything).
    named = [
        entry for entry in ran if _names_a_command(entry)
    ] if isinstance(ran, list) else [key for key in ran if not _is_placeholder(str(key))]
    if not named:
        return True
    outcomes = ran_check_outcomes(result)
    return len(outcomes) == len(named) and all(
        word == _known_checks.LISTED_NOT_RUN for word in outcomes.values()
    )


def _with_ran_failures(
    findings: Optional[List[str]], ran: Dict[str, str],
) -> Optional[List[str]]:
    """*findings* with one added for each command ``ran`` says failed that no
    finding names (``known_checks.with_listed_failures``): a reply whose
    ``passed`` says true beside a failed command is never a clean pass.

    It only adds. A ``ran`` naming no failure leaves a
    ``passed: false`` that named nothing a failing check
    (:data:`CHECK_FAILED_WITHOUT_FINDINGS`), as the native leg records it;
    round 26 read it as a pass through ``with_listed_failures``' rule for an
    apply-code-fixes batch's ``listed``, which stays
    ``listed``'s alone. A failed command added stands in for that bare
    placeholder, as the native host names the command instead."""
    failed = {
        command: word for command, word in ran.items() if word == _ran_word("failed")
    }
    if not failed:
        return findings
    current = _known_checks.with_listed_failures(findings, failed) or []
    if len(current) > 1 and current[0] == _known_checks.CHECK_FAILED_WITHOUT_FINDINGS:
        current = current[1:]
    return current


def _report_check_evidence(result: Any) -> Optional[Dict[str, Any]]:
    """A readable check object to retain across a report-only re-ask.

    A restatement runs no check, so it cannot retract the original turn's
    evidence. Keep the whole object, including ``listed`` and any extra
    detail, when the existing lenient readers can use it. A missing or
    unreadable check remains repairable rather than pinning an unknown
    result over a useful correction.
    """
    check = result.get("check") if isinstance(result, dict) else None
    if not isinstance(check, dict):
        return None
    if (
        batch_check_findings(result) is not None
        or _known_checks.listed_check_outcomes(check.get("listed"))
        # "I ran no check" is an answer too; a restatement
        # cannot turn it into a pass.
        or ran_no_check(result)
    ):
        return copy.deepcopy(check)
    return None


#: How much of one declined item's reason a row, a stamp or a notice carries.
DECLINED_REASON_MAX_CHARS = 300


def declined_reason(text: Any) -> str:
    """One declined item's reason as every record carries it: the batch's
    own words, whitespace collapsed and bounded; ``""`` for no text.

    Both legs read a reason through here: the executor's
    :func:`declined_items` and ``util batch-done --declined``, and
    :func:`row_declined` reads a record back through it.

    The closing full stop is kept.
    ``processed_<phase>``, the write mirror, the verdict stamp and the report
    dropped it while the reply, the log and the host's summary.md kept it.
    A line that puts its own punctuation right after a reason drops the
    reason's one there (``text_clip.without_closing_mark``: the
    ``[BATCH_DECLINED]`` line, the stop and log text, the notes, ``status``),
    so a reason is still printed with one full stop (the decline fixture,
    2026-10-07: "… MAX_SPEED.."); a reason of ``...`` or ``.`` stays a
    reason.
    """
    if not isinstance(text, str):
        return ""
    reason = " ".join(text.split())
    # Cut at a word and marked, never mid-word.
    return clip(reason, DECLINED_REASON_MAX_CHARS)


@dataclass
class DeclinedItems:
    """What a write reply's ``declined`` says, read against its batch.

    ``items`` maps each expected id the batch declined — not also in ``ids``,
    with a non-empty reason — to that reason, in the batch's own order.
    ``conflicting`` holds the ids the reply put in both ``ids`` and
    ``declined``: neither claim stands, so such an id is not attested at all.
    ``problems`` names every other entry that could not be read as a decline
    (an id the batch does not hold, an entry without an id or a reason, a
    value that is not a list of objects), in plain words for the stop.
    """

    items: Dict[str, str] = field(default_factory=dict)
    conflicting: List[str] = field(default_factory=list)
    problems: List[str] = field(default_factory=list)


def declined_items(
    result: Any, expected_ids: Sequence[str],
) -> DeclinedItems:
    """Read a write reply's ``declined`` leniently against *expected_ids*.

    Codex racing run 7: a batch applied
    one fix and left the other on purpose ("Not applied; T011 records the
    clamp removal as deliberate"), said so only in ``notes``, and stopped as
    a partial application on the run and on its resume; the contract had no
    place for a decline. A reason is what makes a decline: an entry without
    one is a problem, and its id reads as not having come back, as an id
    missing from ``ids`` always has. Never read from ``notes``.
    """
    out = DeclinedItems()
    raw = result.get("declined") if isinstance(result, dict) else None
    if raw is None:
        return out
    expected = [str(item) for item in expected_ids]
    reported = result.get("ids") if isinstance(result, dict) else None
    applied = {str(item) for item in reported} if isinstance(reported, list) else set()
    if not isinstance(raw, list):
        out.problems.append("`declined` is not a list")
        return out
    found: Dict[str, str] = {}
    for index, entry in enumerate(raw, 1):
        if not isinstance(entry, dict):
            out.problems.append(f"`declined` entry {index} is not an object")
            continue
        item = entry.get("id")
        item = str(item).strip() if isinstance(item, (str, int)) else ""
        if not item:
            out.problems.append(f"`declined` entry {index} names no id")
            continue
        if item not in expected:
            out.problems.append(
                f"`declined` names {item!r}, which this batch does not hold"
            )
            continue
        if item in applied:
            if item not in out.conflicting:
                out.conflicting.append(item)
                out.problems.append(f"{item} is in both `ids` and `declined`")
            continue
        reason = declined_reason(entry.get("reason"))
        if not reason:
            out.problems.append(f"`declined` gives no reason for {item}")
            continue
        found.setdefault(item, reason)
    out.items = {item: found[item] for item in expected if item in found}
    return out


def row_declined(row: Any) -> Dict[str, str]:
    """A serialized row's (or verdict stamp's) declined items, ``{id: reason}``."""
    raw = row.get("declined") if isinstance(row, dict) else None
    out: Dict[str, str] = {}
    for entry in raw if isinstance(raw, list) else []:
        if isinstance(entry, dict) and entry.get("id") and entry.get("reason"):
            # As recorded (a record from has no closing
            # stop; one from before `declined_reason` reads the same way).
            reason = declined_reason(str(entry["reason"])) or str(entry["reason"])
            out.setdefault(str(entry["id"]), reason)
    return out


#: summary.md's sections for an apply phase's items that were not applied, written by
#: the executor's summary and named by the native
#: runbooks' template and `util batch-done`'s `[BATCH_DECLINED]` /
#: `[BATCH_SKIPPED]` lines.
DECLINED_SECTION_HEADING = "Declined by their batch (not applied)"
SKIPPED_SECTION_HEADING = "Skipped at your request (not applied)"


def declined_record(items: Dict[str, str]) -> List[Dict[str, str]]:
    """The ``declined`` list a row, a verdict stamp and a mirror row carry."""
    return [{"id": item, "reason": reason} for item, reason in items.items()]


def row_batch_check_findings(row: Dict[str, Any]) -> List[str]:
    """A serialized row's own-check findings (its ``batch_check``), else ``[]``."""
    check = row.get("batch_check") if isinstance(row, dict) else None
    if not isinstance(check, dict):
        return []
    return [str(item) for item in (check.get("findings") or []) if str(item)]


def _row_findings_by_check(row: Dict[str, Any], key: str) -> Dict[str, List[str]]:
    """A serialized row's ``{check id: [finding, ...]}`` map under *key*,
    empty findings and empty lists dropped, else ``{}``."""
    found = row.get(key) if isinstance(row, dict) else None
    if not isinstance(found, dict):
        return {}
    return {
        str(check_id): [str(item) for item in items if str(item)]
        for check_id, items in found.items()
        if isinstance(items, list) and any(str(item) for item in items)
    }


def row_batch_check_accepted(row: Dict[str, Any]) -> Dict[str, List[str]]:
    """A serialized row's own-check findings that only repeat what the user
    accepted, by check id (its ``batch_check_accepted``)."""
    return _row_findings_by_check(row, "batch_check_accepted")


def row_batch_check_repeats(row: Dict[str, Any]) -> Dict[str, List[str]]:
    """A serialized row's own-check findings that are the same findings a
    check task of the run reported, by that check's id (its
    ``batch_check_repeats``)."""
    return _row_findings_by_check(row, "batch_check_repeats")


def row_batch_check_note(row: Dict[str, Any]) -> Optional[str]:
    """A serialized row's own-check note (its ``batch_check_note``), else ``None``."""
    note = row.get("batch_check_note") if isinstance(row, dict) else None
    if not isinstance(note, str):
        return None
    return clip(note, CHECK_NOTE_MAX_CHARS) or None


def row_outcome_label(row: Dict[str, Any]) -> Optional[str]:
    """A serialized row's label: ``outcome_label`` when present, else ``write_outcome``.

    Only a verification-only row carries ``outcome_label`` (every other row
    is byte-identical to before), so a reader asks this rather than either key.
    """
    return row.get("outcome_label") or row.get("write_outcome")


def check_record(findings: Sequence[str]) -> Dict[str, Any]:
    """The ``check`` object a row, a verdict stamp and a mirror row carry."""
    return {"passed": not findings, "findings": list(findings)}


def row_check_findings(row: Dict[str, Any]) -> List[str]:
    """A serialized row's check findings (its ``check`` object), else ``[]``."""
    check = row.get("check") if isinstance(row, dict) else None
    if not isinstance(check, dict):
        return []
    return [str(item) for item in (check.get("findings") or []) if str(item)]


WRITE_SCHEMA_REJECTED = "schema-rejection"
WRITE_POLICY_VIOLATION = "policy-violation"

#: Write outcomes that stop the batch loop at its boundary (D3g/D3n): the phase is
#: not completed, snapshots stay in place, and the run exits 3 naming the restore
#: command — under ``--yes`` too, since an unattended run may not decide that a
#: half-applied plan file is acceptable.
WRITE_STOP_OUTCOMES = frozenset({WRITE_PARTIAL, WRITE_POLICY_VIOLATION})
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