hashgraph-online/awesome-codex-plugins / plugins/beastlabai/multi-llm-plugin/skills/multi-llm
multi-llm
FlaggedOrchestrate 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.
utils/html_report_generator.py
View on GitHub"""HTML report generator for validated suggestion groups.
Generates interactive HTML reports from grouped.json data with
model badges, section context previews, and embedded log snippets.
Supports both grouped.json and consolidated.json as data sources.
"""
if __name__ == "__main__" and not __package__:
# Run by path: put the skill root on sys.path, found from this file's real
# location as Python finds sys.path[0], then call the package module's entry
# point with sys.argv untouched, so the program name stays the one typed
# (docs/development/dispatcher.md#import-safety).
import os
import sys
_UTILS_DIR = os.path.dirname(os.path.realpath(__file__))
sys.path[:] = [os.path.dirname(_UTILS_DIR)] + [
p for p in sys.path if os.path.realpath(p) != _UTILS_DIR]
from utils.html_report_generator import main
sys.exit(main(sys.argv[1:]))
import argparse
import base64
import hashlib
import json
import logging
import os
import re
import sys
import warnings
from pathlib import Path
from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence, Set, Tuple
from .atomic_io import atomic_write_text
from .state_file import read_document as _read_state_document
from .stream_bootstrap import bootstrap_streams
from .json_extractor import sanitize_model_name
from .metrics import describe_usage
from .judge_vocab import (
JUDGE_AUTO_DECIDE,
JUDGE_AUTO_DECIDE_SALVAGE,
JUDGE_DECIDED,
canonical_value,
upgrade_legacy,
)
from . import scope_report as _scope_report
from . import importance as _importance
from .process_state import process_cache
logger = logging.getLogger(__name__)
def _write_atomic(path: Path, text: str) -> None:
"""Write *text* by ``atomic_io``'s atomic write, so a reader (the apply
step, a decision overlay, a browser) sees the old file or the new one,
never part of one. UTF-8, the platform's newlines, as ``write_text``."""
atomic_write_text(path, text, newline=os.linesep)
# ---------------------------------------------------------------------------
# Model icon mapping — maps model families to OpenRouter icon data URIs
# ---------------------------------------------------------------------------
# Icons directory (SVGs downloaded from OpenRouter)
_ICONS_DIR = Path(__file__).parent.parent / "assets" / "icons"
# Cache of loaded icon data URIs
_icon_cache: Dict[str, str] = process_cache("utils.html_report_generator._icon_cache")
def _load_icon_data_uri(filename: str) -> str:
"""Load an icon file (SVG or PNG) and return a data URI string."""
if filename in _icon_cache:
return _icon_cache[filename]
icon_path = _ICONS_DIR / filename
if icon_path.exists():
raw = icon_path.read_bytes()
b64 = base64.b64encode(raw).decode("ascii")
mime = "image/svg+xml" if filename.endswith(".svg") else "image/png"
uri = f"data:{mime};base64,{b64}"
else:
uri = ""
_icon_cache[filename] = uri
return uri
def _make_letter_icon_data_uri(letter: str, color: str) -> str:
"""Generate a simple SVG letter icon as a data URI."""
svg = (
f'<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64">'
f'<rect width="64" height="64" rx="14" fill="{color}"/>'
f'<text x="32" y="43" text-anchor="middle" font-family="system-ui,sans-serif" '
f'font-size="36" font-weight="700" fill="white">{letter}</text></svg>'
)
b64 = base64.b64encode(svg.encode()).decode("ascii")
return f"data:image/svg+xml;base64,{b64}"
# Mapping from icon key to (icon_filename_or_None, fallback_letter, fallback_color)
#
# Provenance rule: Orca's MIT grant covers its
# copyright in the PNGs it bundles, NOT the third-party trademarks they depict.
# So Orca is used only as the *catalog* — which agent wears which mark — and each
# asset here is fetched from the vendor's own favicon/brand source, preferring
# SVG. A mark with no reachable first-party SVG gets the letter-icon fallback
# rather than a redrawn or re-hosted logo.
_ICON_DEFS: Dict[str, tuple] = {
"anthropic": ("Anthropic.svg", "A", "#CC9B7A"),
"openai": ("OpenAI.svg", "O", "#10A37F"),
"google": ("GoogleGemini.svg", "G", "#4285F4"),
"xai": ("xAI.svg", "X", "#1DA1F2"),
"moonshotai": ("MoonshotAI.svg", "K", "#5C3DAA"),
"zhipu": ("Zhipu.png", "Z", "#3366FF"),
"minimax": ("MiniMax.png", "M", "#FF6633"),
"cursor": ("Cursor.svg", "C", "#1E1E1E"),
"kilocode": ("Kilocode.svg", "K", "#FF4444"),
"opencode": ("Opencode.svg", "O", "#333333"),
"codex": ("Codex.svg", "C", "#111111"),
"nvidia": ("Nvidia.svg", "N", "#77B900"),
"qwen": ("Qwen.svg", "Q", "#615CED"),
# SVG sourced from mistral.ai/favicon.svg
"mistral": ("Mistral.svg", "M", "#FA520F"),
# SVG sourced from block/goose:ui/desktop/src/images/icon.svg
"goose": ("Goose.svg", "G", "#0F172A"),
# SVG sourced from pi.dev/favicon.svg
"pi": ("Pi.svg", "P", "#09090B"),
# SVG sourced from Primer Octicons' copilot-16 icon (MIT)
"copilot": ("Copilot.svg", "C", "#24292F"),
# SVG sourced from omp.sh/favicon.svg (oh-my-pi's own docs site)
"omp": ("OhMyPi.svg", "O", "#9B4DFF"),
# No first-party SVG reachable — letter-icon fallback only
"xiaomi": (None, "M", "#FF6900"),
"arcee": (None, "T", "#3B82F6"),
"vercel": (None, "V", "#F45B25"),
"deepseek": (None, "D", "#4D6BFE"),
"cline": (None, "C", "#0EA5A4"),
"aider": (None, "A", "#14B8A6"),
# Google Antigravity keeps its own key rather than borrowing "google": the
# Gemini mark would mislabel the CLI as the model family it fans out to.
"antigravity": (None, "A", "#4285F4"),
# Orca's catalog has no mark for muse either — letter icon is the outcome,
# not a placeholder waiting on a fetch.
"muse": (None, "M", "#7C3AED"),
}
# Provider (CLI tool) → icon key. Used to render a provider icon alongside
# the model's company icon when they differ. One row per registered adapter,
# naming a key of _ICON_DEFS: tests/test_provider_roster.py compares it with the
# registry (docs/development/providers.md#adding-a-provider-adapter).
_PROVIDER_ICON_KEYS: Dict[str, str] = {
"claude-code": "anthropic",
"gemini": "google",
"codex": "codex",
"cursor-agent": "cursor",
"kilocode": "kilocode",
"opencode": "opencode",
"grok": "xai",
# Vercel fx is a CLI identity; model-family icons are resolved separately.
"fx": "vercel",
"cline": "cline",
"goose": "goose",
"aider": "aider",
"agy": "antigravity",
"muse": "muse",
"pi": "pi",
"copilot": "copilot",
"kimi": "moonshotai",
"qwen-code": "qwen",
"vibe": "mistral",
# oh-my-pi keeps its own key rather than borrowing "pi": omp fans out
# across model families, so a borrowed mark would mislabel the CLI as one
# of them — the same reason "antigravity" above is not "google".
"omp": "omp",
}
def _get_icon_data_uri(icon_key: str) -> str:
"""Get icon data URI for a given icon key."""
if icon_key not in _ICON_DEFS:
return ""
svg_file, letter, color = _ICON_DEFS[icon_key]
if svg_file:
uri = _load_icon_data_uri(svg_file)
if uri:
return uri
return _make_letter_icon_data_uri(letter, color)
def _resolve_model_icon_key(provider: str, model_name: str) -> str:
"""Determine the icon key for a provider:model combination.
Maps the model name (and provider as fallback) to the underlying AI
company whose icon should be displayed.
"""
full = f"{provider}:{model_name}".lower()
model_lower = model_name.lower()
# Check model name patterns first (most specific)
if any(k in model_lower for k in ("sonnet", "opus", "haiku", "claude")):
return "anthropic"
if any(k in model_lower for k in ("gpt", "codex", "o1", "o3", "o4")):
return "openai"
if "gemini" in model_lower:
return "google"
if "grok" in model_lower:
return "xai"
if any(k in full for k in ("kimi", "moonshot")):
return "moonshotai"
if any(k in full for k in ("glm", "z-ai", "zhipu")):
return "zhipu"
if "minimax" in full:
return "minimax"
if any(k in full for k in ("nemotron", "nvidia")):
return "nvidia"
if "qwen" in full:
return "qwen"
if "deepseek" in full:
return "deepseek"
if "mistral" in full:
return "mistral"
if any(k in full for k in ("mimo", "xiaomi")):
return "xiaomi"
if any(k in full for k in ("trinity", "arcee")):
return "arcee"
# Fall back to the provider's own icon when no model-family pattern matched
return _PROVIDER_ICON_KEYS.get(provider.lower(), "")
def _resolve_provider_icon_key(provider: str) -> str:
"""Return the icon key for the invocation provider (CLI tool) itself."""
return _PROVIDER_ICON_KEYS.get(provider.lower(), "")
# ---------------------------------------------------------------------------
# Canonical sort-order constants (single source of truth for the codebase)
# ---------------------------------------------------------------------------
VALIDATION_ORDER = {
"needs-human-decision": 0,
"valid": 1,
"validation_failed": 2,
"invalid": 3,
"pending": 4,
}
UNKNOWN_STATUS_RANK = 5
# The rank table is `utils/importance.py`'s; "" is a group with no members,
# which sorts after LOW. The templates sort by this table (`sortConfig`).
IMPORTANCE_ORDER = {**_importance.RANK, "": _importance.UNKNOWN_RANK}
UNKNOWN_IMPORTANCE_RANK = _importance.UNKNOWN_RANK
# ---------------------------------------------------------------------------
# Shared sorting helpers
# ---------------------------------------------------------------------------
def compute_max_importance(suggestions: Optional[List[Dict[str, Any]]]) -> str:
"""Return the importance of a group or bucket holding *suggestions*.
The rule apply filters by (``importance.members_importance``): the
highest level, in either case, a suggestion naming none counting as
MEDIUM as its own badge does. Returns ``""`` only when *suggestions* is
``None`` or empty — this maps to ``IMPORTANCE_ORDER[""]`` (after LOW) so
that empty groups sort last within their validation-status tier.
"""
return _importance.members_importance(suggestions, empty="")
def _sort_by_priority(
items: List[Dict[str, Any]],
status_fn: Callable[[Dict[str, Any]], str],
importance_fn: Callable[[Dict[str, Any]], str],
) -> List[Dict[str, Any]]:
"""Generic priority sort. Stamps ``originalIndex``, returns a new sorted list.
Args:
items: List of group dicts to sort.
status_fn: Callable(item) -> str — extracts the validation status string.
importance_fn: Callable(item) -> str — extracts the importance string.
"""
for i, item in enumerate(items):
if "originalIndex" not in item:
item["originalIndex"] = i + 1
def _key(item):
return (
VALIDATION_ORDER.get(status_fn(item), UNKNOWN_STATUS_RANK),
IMPORTANCE_ORDER.get(importance_fn(item), UNKNOWN_IMPORTANCE_RANK),
item.get("originalIndex", 0),
)
return sorted(items, key=_key)
def sort_groups_by_priority(
groups: List[Dict[str, Any]],
) -> List[Dict[str, Any]]:
"""Sort camelCase report-data dicts (post ``_build_group_data()``)."""
return _sort_by_priority(
groups,
status_fn=lambda g: g.get("validationStatus", ""),
importance_fn=lambda g: g.get("maxImportance", ""),
)
def sort_raw_groups_by_priority(
groups: List[Dict[str, Any]],
) -> List[Dict[str, Any]]:
"""Sort raw snake_case grouped.json dicts."""
return _sort_by_priority(
groups,
status_fn=lambda g: g.get("validation_status") or "",
importance_fn=lambda g: _importance.group_importance(g, empty=""),
)
def sort_consolidated_groups_by_priority(
groups: List[Dict[str, Any]],
) -> List[Dict[str, Any]]:
"""Sort consolidated group dicts (direct importance field, aggregate status)."""
return _sort_by_priority(
groups,
status_fn=lambda g: g.get("validation_status") or "",
importance_fn=lambda g: _importance.normalize(g.get("importance"), ""),
)
def derive_aggregate_validation_status(
statuses: List[str],
) -> str:
"""Derive aggregate validation status from a list of constituent statuses.
Selects the status with the **lowest** ``VALIDATION_ORDER`` rank (i.e.,
highest priority wins). Statuses not listed in ``VALIDATION_ORDER``
receive ``UNKNOWN_STATUS_RANK`` and lose to all recognised statuses.
Returns ``""`` when *statuses* is empty.
"""
if not statuses:
return ""
# Use min() on rank — lowest rank = highest priority
return min(
statuses,
key=lambda s: VALIDATION_ORDER.get(s, UNKNOWN_STATUS_RANK),
)
def build_sort_config() -> Dict[str, Any]:
"""Build the ``sortConfig`` object for injection into HTML report data."""
return {
"validationOrder": VALIDATION_ORDER,
"importanceOrder": IMPORTANCE_ORDER,
"unknownStatusRank": UNKNOWN_STATUS_RANK,
"unknownImportanceRank": UNKNOWN_IMPORTANCE_RANK,
}
def hsl_to_hex(h: int, s: int, l: int) -> str:
"""Convert HSL values to hex color string.
Args:
h: Hue (0-360)
s: Saturation (0-100)
l: Lightness (0-100)
Returns:
Hex color string (e.g., "#B8860B")
"""
s = s / 100
l = l / 100
c = (1 - abs(2 * l - 1)) * s
x = c * (1 - abs((h / 60) % 2 - 1))
m = l - c / 2
if h < 60:
r, g, b = c, x, 0
elif h < 120:
r, g, b = x, c, 0
elif h < 180:
r, g, b = 0, c, x
elif h < 240:
r, g, b = 0, x, c
elif h < 300:
r, g, b = x, 0, c
else:
r, g, b = c, 0, x
r = int((r + m) * 255)
g = int((g + m) * 255)
b = int((b + m) * 255)
return f"#{r:02X}{g:02X}{b:02X}"
def string_to_color(s: str) -> str:
"""Generate a consistent color from a string using hash.
Uses HSL color space to produce visually distinct, pleasant colors.
Same string always produces the same color.
Args:
s: Input string (e.g., model name "claude-3-opus")
Returns:
Hex color string (e.g., "#B8860B")
"""
if not s:
return "#6B7280" # Default gray for empty string
# Hash the string
hash_bytes = hashlib.md5(s.encode()).digest()
# Use first 3 bytes to generate HSL values
# Hue: full 0-360 range
hue = (hash_bytes[0] + hash_bytes[1] * 256) % 360
# Saturation: 50-70% for good color visibility
saturation = 50 + (hash_bytes[2] % 21)
# Lightness: 45-55% for readability on both light/dark backgrounds
lightness = 45 + (hash_bytes[3] % 11)
# Convert HSL to RGB then to hex
return hsl_to_hex(hue, saturation, lightness)
def parse_model_string(model_string: str) -> tuple[str, str]:
"""Parse a model string into provider and model name components.
Handles formats like:
- "anthropic:claude-3-opus" -> ("anthropic", "claude-3-opus")
- "openai:gpt-4" -> ("openai", "gpt-4")
- "claude-3-opus" -> ("", "claude-3-opus")
Args:
model_string: Full model identifier
Returns:
Tuple of (provider, model_name). Provider is empty string if not present.
"""
if not model_string:
return ("", "")
if ":" in model_string:
parts = model_string.split(":", 1)
return (parts[0], parts[1])
return ("", model_string)
def get_model_metadata(model_string: str) -> Dict[str, Any]:
"""Get color info for model badges using hash-based color generation.
Generates separate consistent colors for provider and model name.
Same provider always produces the same provider color.
Same model name always produces the same model color.
Args:
model_string: Full model identifier (e.g., "anthropic:claude-3-opus", "gpt-4")
Returns:
Dict with:
- 'full': The original model string
- 'provider': Provider name (empty string if not present)
- 'model': Model name
- 'provider_color': Color for provider badge (gray if no provider)
- 'model_color': Color for model badge
"""
provider, model_name = parse_model_string(model_string)
model_icon_key = _resolve_model_icon_key(provider, model_name)
provider_icon_key = _resolve_provider_icon_key(provider)
model_icon_uri = _get_icon_data_uri(model_icon_key) if model_icon_key else ""
# Only emit the provider icon when it's distinct from the model icon —
# avoids duplicate logos when the CLI and model are the same brand
# (e.g. claude-code:opus, gemini:gemini-2.5-pro).
provider_icon_uri = (
_get_icon_data_uri(provider_icon_key)
if provider_icon_key and provider_icon_key != model_icon_key
else ""
)
return {
"full": model_string,
"provider": provider,
"model": model_name,
"provider_color": string_to_color(provider) if provider else "#6B7280",
"model_color": string_to_color(model_name),
"icon": model_icon_uri,
"provider_icon": provider_icon_uri,
}
def _attribution_notes(model: str, entry: Any) -> List[str]:
"""The provenance notes one ``served_models`` entry is worth, in order.
Split out of :func:`served_model_label` so the usage clause can join the
*same* parenthesis rather than opening a second one after it: a line
reading ``model (served by X, fallback) ($0.04 est.)`` says the notes come
from two unrelated systems, which is exactly backwards — they are two
facts about one slot.
"""
if not isinstance(entry, dict):
return []
notes: List[str] = []
served = entry.get("served_model")
# A primary that served its own turn is not an attribution note: it is the
# model already printed at the head of the label.
if served and served != model:
notes.append(
f"served by {served}, fallback" if entry.get("fallback")
else f"served by {served}"
)
sandbox = entry.get("sandbox")
if sandbox == "bypassed":
notes.append(SANDBOX_BYPASSED_LABEL)
elif isinstance(sandbox, str) and sandbox.startswith(SANDBOX_FALLBACK_WORD_PREFIX):
notes.append(sandbox_fallback_label(sandbox))
# A slot the plugin's jail failed keeps its rung on the record
# (F1 item 6); its reason rides the same parenthesis.
denied = jail_denied_label(entry)
if denied:
notes.append(denied)
return notes
def served_model_label(
model: str, served_models: Optional[Dict[str, Any]] = None
) -> str:
"""``model`` as a report label, carrying the served-model attribution.
One renderer for every markdown surface that names a model *without* a
cost beside it (the code review's per-issue ``**Model:**`` field, which
repeats per finding and where a token count would be noise), so a fallback
reads the same wherever it surfaces. Without an entry — which is every run
under the shipped, empty ``fallback_models`` — the bare model string is
returned and the report is byte-for-byte what it was. The summary lines
that *do* name a cost use :func:`model_label`, which is this plus the
usage clause in the same parenthesis.
The D6 override's provenance renders on the same label:
``sandbox: "bypassed"`` in the entry appends ``ran unsandboxed:
sandbox_fallback=auto``, so a report reader sees which slot's findings
came from a model that ran with the operator's shell rights — beside the
served-model note when both apply, alone when only one does. A slot on a
**contained** fallback rung (``sandbox: "fallback-landlock"``, 2026-09-22)
is not unsandboxed and never gets that label: it gets
:func:`sandbox_fallback_label` instead, which names the rung.
"""
notes = _attribution_notes(model, (served_models or {}).get(model))
if not notes:
return model
return f"{model} ({'; '.join(notes)})"
def model_label(
model: str,
served_models: Optional[Dict[str, Any]] = None,
usage: Optional[Dict[str, Any]] = None,
) -> str:
""":func:`served_model_label` plus what the slot spent, in one parenthesis.
The renderer for the summary lines that name each model once — the
aggregate's ``**Models:**`` line in both lanes. ``usage`` is the fan-out's
``{model_spec: usage}`` map (``.status.json``'s ``usage`` key); a model
with no entry renders exactly what it rendered before, which is the rule
that keeps a report from a duration-only adapter free of ``$0.00``.
``describe_usage`` is the same clause the failed-slot error line and the
HTML badge carry, imported rather than re-spelled: a report that quoted a
cost in a second format would be a second answer to "what did this run
cost", and the two would drift apart at the first rounding change.
"""
notes = _attribution_notes(model, (served_models or {}).get(model))
clause = describe_usage((usage or {}).get(model))
if clause:
notes.append(clause)
if not notes:
return model
return f"{model} ({'; '.join(notes)})"
def sum_usage(usage: Optional[Dict[str, Any]]) -> Dict[str, Any]:
"""Column-wise sum of a fan-out's per-model usage blocks, or ``{}``.
What the run cost in total, which is the number an operator looks for
first and the one no artifact carried before Stage U. Summed by key over
whichever models reported, so a fan-out of one reporting adapter and two
duration-only ones totals the one — the alternative, refusing to total a
mixed run, would report nothing for the common case.
**It is the run's total, not the badges' total.** The map handed in covers
every slot that reported, including the ones that FAILED and therefore have
no badge in this report at all, so the header figure can exceed the sum of
what is displayed. That is the intended reading: the question is what the
run cost, and the slot that burned a budget and returned nothing is the
most expensive kind of answer there is.
**Only numbers are added.** A usage block is an adapter's, and at least one
adapter files a string in it (claude-code's ``served_model``, which rides
the envelope its token counts came from). Anything that is not an ``int``
or ``float`` is skipped rather than coerced, and ``bool`` is excluded
because in Python it is an ``int`` and "1 tool use" is not what
``True`` meant. Float sums are rounded to six places: ``0.01 + 0.02``
is ``0.030000000000000002`` in binary floating point, and a report
header is not the place to show it.
"""
totals: Dict[str, Any] = {}
for entry in (usage or {}).values():
if not isinstance(entry, dict):
continue
for key, value in entry.items():
if isinstance(value, bool) or not isinstance(value, (int, float)):
continue
totals[key] = totals.get(key, 0) + value
return {
key: round(value, 6) if isinstance(value, float) else value
for key, value in totals.items()
}
#: The clause a failed model's entry carries when this attempt asked for a
#: salvage of it and the model is still failed. Fixed text on both lanes (the
#: live native request and the ``--exec-subagents`` unrecoverable one): the
#: subagent's own reason stays on its ``[SALVAGE_UNRECOVERABLE]`` stdout line,
#: so the header never quotes a second, paraphrased cause.
SALVAGE_REQUESTED_CLAUSE = "salvage requested, nothing recovered"
#: The label of the failure line, shared by ``report.md``'s bold header line and
#: the HTML warning notice built from the same text without the bold markers.
FAILED_MODELS_LABEL = "Models failed:"
def _one_line(text: Any) -> str:
"""*text* with every line break folded to a space.
A stored failure reason is provider output and can carry a newline, which
would end a markdown header line early — and in ``code-review``'s
``report.md`` a line that starts ``### N.`` after a blank one is an issue
header the apply phase's parser reads a Skip box under. So the reason is
verbatim apart from its line breaks.
"""
return " ".join(str(text).replace("\r\n", "\n").replace("\r", "\n").split("\n"))
def failed_models_line(
failed_models: Optional[Dict[str, Any]],
requested_models: Optional[int] = None,
salvage_requested: Optional[Sequence[str]] = None,
*,
bold: bool = True,
served_models: Optional[Dict[str, Any]] = None,
) -> str:
"""The one-line account of the models that produced no result, or ``""``.
``**Models:**`` names only the models that produced results, so a reviewer
that timed out used to be absent from every surface above the fold. This is the
line that goes directly under it — and, with ``bold=False``, the HTML
warning notice's ``message`` — so ``report.md`` and ``report.html`` are
built from one string and cannot disagree::
**Models failed:** 1 of 5 requested — pi:x/y: pi timed out after 1200s; salvage requested, nothing recovered
Args:
failed_models: ``{spec: reason}``; each reason is rendered verbatim
(line breaks folded, see :func:`_one_line`). Empty or ``None``
renders nothing.
requested_models: The size of the requested set, never succeeded plus
failed (a requested model with neither a result nor a recorded
failure is in neither). ``None`` when the caller has no requested
set, and the line then states the count without "of M".
salvage_requested: The specs whose entry carries
:data:`SALVAGE_REQUESTED_CLAUSE` — the caller's answer to "did this
attempt ask for a salvage of this still-failed model"
(``review_orchestrator_base.salvage_requested_models``).
bold: ``True`` for the markdown header line, ``False`` for the notice.
served_models: ``models_served``. A slot whose entry
there carries ``failure_reason: jail-denied`` leads with ``denied
by the plugin's jail: <path>`` — the record outlives the log that
printed the ``[JAIL_DENIED]`` line — and keeps
its recorded reason after it (a later ``[CODEX_HOME_CHECK]`` or
``[MODE_CHECK]`` violation, code-review's ``(spent $X)``), unless
that reason already carries the label.
"""
if not failed_models:
return ""
salvaged = {str(spec) for spec in (salvage_requested or ())}
entries = []
for spec, reason in failed_models.items():
# A record renders through the one reason renderer; a string is
# itself, as before. The served record's jail label is prepended, never
# substituted: the recorded reason can carry what happened after the
# denial (a check violation, the spend clause).
text = failure_reason_text(reason)
denied = jail_denied_label((served_models or {}).get(spec))
if denied and denied not in text:
text = f"{denied}; {text}" if text.strip() else denied
entry = f"{spec}: {_one_line(text)}"
if str(spec) in salvaged:
entry += f"; {SALVAGE_REQUESTED_CLAUSE}"
entries.append(entry)
count = len(failed_models)
if requested_models is not None:
count_text = f"{count} of {int(requested_models)} requested"
else:
count_text = str(count)
label = f"**{FAILED_MODELS_LABEL}**" if bold else FAILED_MODELS_LABEL
return f"{label} {count_text} — {'; '.join(entries)}"
def build_report_notices(
notices: Optional[Sequence[Any]],
failed_models: Optional[Dict[str, Any]] = None,
requested_models: Optional[int] = None,
salvage_requested: Optional[Sequence[str]] = None,
served_models: Optional[Dict[str, Any]] = None,
) -> List[Dict[str, str]]:
"""``reportData.notices``: the failure warning first, then *notices*.
Every template's ``renderNotices`` prints ``escapeHtml(n.message)`` and
nothing else, so a notice without a ``message`` renders as an empty
coloured bar. Nothing reaches the list without a non-empty one — the
data-source notices are filtered on the same rule — and the failure
notice exists only when :func:`failed_models_line` has something to say.
Shared by the phase report and the consolidated report so both pages
carry the same bar.
"""
result: List[Dict[str, str]] = []
failure = failed_models_line(
failed_models, requested_models, salvage_requested, bold=False,
served_models=served_models,
)
if failure:
result.append({"type": "warning", "message": failure})
for notice in notices or ():
if not isinstance(notice, dict):
continue
message = notice.get("message")
if not isinstance(message, str) or not message.strip():
continue
result.append(notice)
return result
#: The label a bypassed slot carries in every report surface. The config key
#: and its value are spelled out because they name the one setting that
#: decides this (and, by naming ``auto``, the word ``off`` that would have
#: kept the slot out), and the reader of a report is the person who should
#: know it.
SANDBOX_BYPASSED_LABEL = "ran unsandboxed: sandbox_fallback=auto"
#: The ``models_served`` word prefix for a slot on a **contained** fallback
#: rung (``fallback-landlock``) — ``llm_client.SANDBOX_FALLBACK_WORD_PREFIX``,
#: spelled here because this renderer reads recorded data and imports no
#: provider code.
SANDBOX_FALLBACK_WORD_PREFIX = "fallback-"
#: The recorded words of a slot on an **incidental**-grade rung, and the label
#: each renders as. A closed set spelled
#: here, because this renderer reads recorded data and imports no provider
#: code: the plugin's Landlock jail stops stray writes and nothing more, so its
#: slot is never "sandboxed by fallback rung" — the label a real OS boundary
#: earns. A word outside this set keeps the contained wording, as before. The
#: label names no phase, so a read-only slot and a write dispatch share it.
INCIDENTAL_FALLBACK_LABELS: Dict[str, str] = {
"fallback-plugin-landlock": (
"stray writes stopped by plugin-landlock; not a boundary against the model"
),
}
def sandbox_fallback_label(word: str) -> str:
"""The report note for a slot on a fallback rung.
A **contained** rung (``fallback-landlock``) says the slot was sandboxed —
by a fallback boundary, named — because its findings came from a model
whose writes the kernel denied, which is the opposite of what
:data:`SANDBOX_BYPASSED_LABEL` tells a reader. An **incidental** rung
(:data:`INCIDENTAL_FALLBACK_LABELS`, 2026-09-30) says what it stops and
that it is not a boundary against the model, never "sandboxed".
"""
incidental = INCIDENTAL_FALLBACK_LABELS.get(word)
if incidental is not None:
return incidental
rung = word[len(SANDBOX_FALLBACK_WORD_PREFIX):] if word.startswith(
SANDBOX_FALLBACK_WORD_PREFIX
) else word
return f"sandboxed by fallback rung: {rung}"
#: The per-slot failure reason a jailed slot records when codex itself died on
#: an EACCES the plugin's jail caused, and the key carrying the denied path. Spelled here
#: for the same reason as :data:`INCIDENTAL_FALLBACK_LABELS`: the fan-out's
#: ``llm_client`` sets ``failure_reason: "jail-denied"`` on the slot's record,
#: and the report reads the record, never the provider code.
JAIL_DENIED_REASON = "jail-denied"
JAIL_DENIED_PATH_KEY = "jail_denied_path"
#: What the jail-denied label says when codex named no path (the probable-jail
#: class of ``landlock_dispatch.is_jail_failure``).
JAIL_DENIED_NO_PATH = "path not named"
def jail_denied_label(record: Any) -> Optional[str]:
"""``denied by the plugin's jail: <path>`` for a slot record whose
``failure_reason`` is ``jail-denied``, else ``None``.
Generic over the record's shape: a ``failed_models`` value, a
``models_served`` entry or a ``progress.models`` row all carry the same two
keys, so the report and ``status`` show the same words after the log that
printed the ``[JAIL_DENIED]`` line is gone.
"""
if not isinstance(record, Mapping):
return None
if record.get("failure_reason") != JAIL_DENIED_REASON:
return None
path = record.get(JAIL_DENIED_PATH_KEY)
return f"denied by the plugin's jail: {path or JAIL_DENIED_NO_PATH}"
def failure_reason_text(reason: Any) -> str:
"""A ``failed_models`` value as the one reason a report line carries.
A string is itself (every lane today). A record is its
jail-denied label when it carries one, else its ``error``/``reason`` text —
so a lane that starts recording a dict never renders as a Python repr.
"""
if isinstance(reason, Mapping):
label = jail_denied_label(reason)
if label:
return label
text = reason.get("error") or reason.get("reason")
return str(text) if text else "failed with no error recorded"
return str(reason)
_FENCE_RUN = re.compile(r"(`{3,}|~{3,})")
def _heading_levels(lines: Sequence[str]) -> Dict[int, int]:
"""``{line index: level}`` for every markdown heading among *lines*.
The one definition of a heading the report uses: one to six ``#`` then a
space or tab, outside fenced code (a shell comment is not a heading, and
neither is ``#hashtag``). Fences follow CommonMark, as the page's ``marked``
does: a fence closes only on a run of its own character at least as long as
the one that opened it, with nothing after it, so a four-backtick block can
quote a three-backtick line.
"""
levels: Dict[int, int] = {}
fence_char, fence_len = "", 0
for index, line in enumerate(lines):
stripped = line.strip()
run = _FENCE_RUN.match(stripped)
if run:
marker = run.group(1)
rest = stripped[run.end():]
if not fence_char:
# A backtick fence's info string cannot hold a backtick.
if not (marker[0] == "`" and "`" in rest):
fence_char, fence_len = marker[0], len(marker)
continue
elif marker[0] == fence_char and len(marker) >= fence_len and not rest:
fence_char, fence_len = "", 0
continue
if fence_char or not stripped.startswith("#"):
continue
level = len(stripped) - len(stripped.lstrip("#"))
if level > 6 or stripped[level:level + 1] not in (" ", "\t"):
continue
levels[index] = level
return levels
def _find_reference_line(lines: Sequence[str], ref: str,
candidates: Optional[Sequence[int]] = None) -> int:
"""The first line *ref* names, or -1: an exact or prefix match on the
stripped line, else the reference's text inside the line's text after its
``#`` markers. *candidates* restricts the search to those line indexes."""
indexes = range(len(lines)) if candidates is None else candidates
ref_lower = ref.lower().strip()
for i in indexes:
line_stripped = lines[i].strip().lower()
if line_stripped == ref_lower or line_stripped.startswith(ref_lower):
return i
ref_text = ref.lstrip('#').strip().lower()
if candidates is not None and not ref_text:
return -1
for i in indexes:
if ref_text in lines[i].lstrip('#').strip().lower():
return i
return -1
def extract_section_contexts(
plan_content: str,
section_refs: Set[str],
full_section: bool = False
) -> Dict[str, str]:
"""Extract context around each referenced section header.
Takes the plan markdown content and a set of section references
(like "### Step 2") and returns surrounding context text for each.
By default, extracts ~15 lines around the first line the reference names,
heading or not (for tooltip/hover use).
When full_section=True, the reference must name a heading
(:func:`_heading_levels`), and the entry is that heading's section: from
it to the next heading of the same or a higher level, nested headings
included. A reference that matches only body text names no section and
gets no entry; its block in the report still renders its suggestions,
under the hover context above. (Taking the enclosing heading's span
instead would repeat a section the report already shows under its own
heading, and for a match above the first ``##`` it is the title's span:
the whole plan.)
Args:
plan_content: The full markdown content of the plan
section_refs: Set of section references to find (e.g., {"### Step 2"})
full_section: If True, capture the full section text of the heading
the reference names instead of ~15 lines around it. Default False.
Returns:
Dict mapping section reference to surrounding context text
"""
if not plan_content or not section_refs:
return {}
lines = plan_content.split('\n')
contexts = {}
headings = _heading_levels(lines) if full_section else {}
heading_indexes = sorted(headings)
for ref in section_refs:
if not ref:
continue
if not full_section:
found_idx = _find_reference_line(lines, ref)
if found_idx >= 0:
# Extract ~15 lines of context (7 before, the line, 7 after)
start = max(0, found_idx - 7)
end = min(len(lines), found_idx + 8)
contexts[ref] = '\n'.join(lines[start:end])
continue
found_idx = _find_reference_line(lines, ref, heading_indexes)
if found_idx < 0:
continue
# The next heading at the same or a higher level (fewer or equal #'s)
# ends the section; deeper ones (#### inside ###) are nested in it.
header_level = headings[found_idx]
end_idx = next(
(j for j in heading_indexes if j > found_idx and headings[j] <= header_level),
len(lines),
)
context_lines = lines[found_idx:end_idx]
# Strip trailing blank lines for cleaner output
while context_lines and context_lines[-1].strip() == '':
context_lines.pop()
contexts[ref] = '\n'.join(context_lines)
return contexts
def extract_plan_section_order(plan_content: str) -> List[str]:
"""Return every section header of the plan, in the order it is written.
This captures the plan's original narrative order so the HTML report can
offer a "Plan Order" view alongside the priority-sorted view — and the
report orders *whatever it buckets by*, so a heading the report can bucket
under must appear here. Restricted to ``###``, it listed only the numbered
task headings: a real 8-task review had six further buckets (Overview,
Design Requirements, Implementation Tasks, File Changes, Testing,
Priority) carrying 31 suggestion references between them, none of which
the "natural" sort could place, so they fell to the arbitrary tail the
template appends.
``##`` and deeper are the sections; a lone top-level ``#`` is the plan's
title, and a section whose text is the whole document is not a section —
so level 1 is used only by a plan that has no other heading level.
Fenced code is skipped, because a shell comment is not a heading. Repeats
are dropped, keeping the first, so the result is usable as a bucket key
list.
"""
if not plan_content:
return []
deep: List[str] = []
top: List[str] = []
lines = plan_content.splitlines()
for index, level in _heading_levels(lines).items():
(top if level == 1 else deep).append(lines[index].strip())
order = deep or top
seen: Set[str] = set()
return [ref for ref in order if not (ref in seen or seen.add(ref))]
def embed_log_snippets(
log_dir: Path,
models: List[str],
max_lines: int = 50
) -> Dict[str, str]:
"""Extract relevant portions of log files for each model.
Looks for log_{model}.txt files in log_dir and returns
the last max_lines of each log file.
Args:
log_dir: Directory containing log files
models: List of model names to look for
max_lines: Maximum number of lines to include (default 50)
Returns:
Dict mapping model name to log content (last max_lines)
"""
log_snippets = {}
if not log_dir.exists():
return log_snippets
for model in models:
# Sanitize model name the same way the log files were actually named
# (utils/json_extractor.sanitize_model_name), or a model with a dot in
# it — e.g. "cursor-agent:composer-2.5" — never matches its own file.
log_file = log_dir / f"log_{sanitize_model_name(model)}.txt"
if not log_file.exists():
# Try without sanitization
log_file = log_dir / f"log_{model}.txt"
if log_file.exists():
try:
content = log_file.read_text(encoding='utf-8', errors='replace')
lines = content.split('\n')
# Get last max_lines
if len(lines) > max_lines:
lines = lines[-max_lines:]
log_snippets[model] = '\n'.join(lines)
except OSError:
pass
return log_snippets
def _build_suggestion_data(
suggestion: Dict[str, Any],
group_index: int,
suggestion_index: int
) -> Dict[str, Any]:
"""Build the data structure for a single suggestion.
Args:
suggestion: Raw suggestion dict from grouped.json
group_index: 1-based group index
suggestion_index: 1-based suggestion index within group
Returns:
Formatted suggestion dict for report data
"""
# Build file reference for code-review style suggestions
file_path = suggestion.get("file", "")
line_range = suggestion.get("line_range")
file_ref = ""
if file_path:
file_ref = file_path
if line_range and isinstance(line_range, (list, tuple)) and len(line_range) >= 2:
file_ref += f":{line_range[0]}-{line_range[1]}"
elif line_range and isinstance(line_range, (list, tuple)) and len(line_range) == 1:
file_ref += f":{line_range[0]}"
# Use stable content hash if available, fall back to positional ID
suggestion_id = suggestion.get(
"suggestion_hash", f"G{group_index}S{suggestion_index}"
)
result = {
"id": suggestion_id,
"title": suggestion.get("title", "Untitled"),
"description": suggestion.get("desc", suggestion.get("description", "")),
"importance": _importance.normalize(suggestion.get("importance")),
"type": suggestion.get("type", "unknown"),
"sectionRef": suggestion.get("reference", suggestion.get("section", "")),
"fileRef": file_ref, # For code-review: file path with line range
"model": suggestion.get("source_model", "unknown"),
# PR-style contextual fields
"anchorText": suggestion.get("anchor_text", None),
"suggestedFix": suggestion.get("suggested_fix", None),
"lineRange": suggestion.get("line_range", None),
}
# Add display label and display hash when available (Phase 1 stamps)
display_label = suggestion.get("display_label")
if display_label is not None:
result["displayLabel"] = display_label
display_hash = suggestion.get("display_hash")
if display_hash is not None:
result["displayHash"] = display_hash
# The reviewer's own (provisional) scope tag; ``Scope unclear`` when the
# finding predates classification.
result[_scope_report.ENTRY_KEY] = _scope_report.member_scope(suggestion)
return result
def _build_group_data(
group: Dict[str, Any],
index: int,
validation_results: Optional[List[Dict[str, Any]]] = None
) -> Dict[str, Any]:
"""Build the data structure for a single group.
Args:
group: Raw group dict from grouped.json
index: 0-based group index
validation_results: Optional validation results list
Returns:
Formatted group dict for report data
"""
# Get validation info from the group itself or from validation_results
validation_status = group.get("validation_status")
validation_reason = group.get("validation_reason", "")
validation_confidence = group.get("validation_confidence", 0.0)
# Try to get from validation_results if not in group
if validation_results and index < len(validation_results):
val_result = validation_results[index]
if validation_status is None:
validation_status = val_result.get("status")
if not validation_reason:
validation_reason = val_result.get("reason", "")
if validation_confidence in (0.0, None):
validation_confidence = val_result.get("confidence", 0.0)
# Build suggestions list
suggestions = []
original_index = group.get("originalIndex", index + 1)
raw_suggestions = group.get("suggestions", group.get("issues", []))
for j, sugg in enumerate(raw_suggestions, start=1):
suggestions.append(_build_suggestion_data(sugg, original_index, j))
# Compute max importance from raw suggestions for sorting
max_importance = compute_max_importance(raw_suggestions)
result = {
"index": index + 1, # 1-based for display
"originalIndex": group.get("originalIndex", index + 1),
"theme": group.get("theme", "Unknown Theme"),
"category": group.get("category", "unknown"),
"models": group.get("models", []),
"priorityScore": group.get("priority_score", 0),
"validationStatus": validation_status or "pending",
"validationReason": validation_reason,
"validationConfidence": validation_confidence,
"maxImportance": max_importance,
"suggestions": suggestions,
}
# A cascade stage's re-raise (the earlier-round entry its validator says
# the group repeats); absent everywhere else, so the data keeps its shape.
reraise = group.get("validation_reraise_of")
if reraise:
result["validationReraiseOf"] = reraise
# Add stable hash fields when available (Phase 1 stamps)
group_hash = group.get("group_hash")
if group_hash is not None:
result["groupHash"] = group_hash
display_label = group.get("display_label")
if display_label is not None:
result["displayLabel"] = display_label
display_hash = group.get("display_hash")
if display_hash is not None:
result["displayHash"] = display_hash
# A commit review's attribution: sibling
# fields of the group, present only when the attribution pass ran, so a
# plan's report data is unchanged.
if "introduced_by_source" in group:
result["introducedBy"] = group.get("introduced_by")
result["introducedBySource"] = group.get("introduced_by_source")
return result
# ---------------------------------------------------------------------------
# Consolidated.json support
# ---------------------------------------------------------------------------
def _validate_consolidated_schema(data: Any) -> bool:
"""Check whether *data* has the expected consolidated.json schema.
Expected shapes:
- Object with ``consolidated_groups`` key whose items contain
``underlying_group_ids`` and ``title``.
- Top-level array of objects with ``underlying_group_ids``.
"""
if isinstance(data, dict):
groups = data.get("consolidated_groups")
if not isinstance(groups, list):
return False
if len(groups) == 0:
return True # Empty is valid
first = groups[0]
return (
isinstance(first, dict)
and "underlying_group_ids" in first
and "title" in first
)
if isinstance(data, list):
if len(data) == 0:
return True
first = data[0]
return isinstance(first, dict) and "underlying_group_ids" in first
return False
def _load_consolidated_groups(
consolidated_path: Path,
) -> Tuple[Optional[List[Dict[str, Any]]], Optional[Dict[str, Any]]]:
"""Load consolidated groups from *consolidated_path*.
Returns ``(groups_list, metadata_dict)`` on success.
Returns ``(None, None)`` if the file is missing or malformed.
Logs a warning on malformed data.
"""
if not consolidated_path.exists():
return None, None
try:
raw = json.loads(consolidated_path.read_text(encoding="utf-8"))
except (json.JSONDecodeError, OSError) as exc:
logger.warning(
"consolidated.json is malformed, falling back to grouped.json: %s", exc
)
return None, None
if not _validate_consolidated_schema(raw):
logger.warning(
"consolidated.json is malformed, falling back to grouped.json"
)
return None, None
if isinstance(raw, list):
return raw, None
# dict form
return raw.get("consolidated_groups", []), raw.get("metadata")
def _build_grouped_lookup(
groups: List[Dict[str, Any]],
) -> Dict[str, Dict[str, Any]]:
"""Build a lookup table mapping group hashes/IDs to their group dicts.
Looks at ``group_hash``, ``group_id``, ``groupHash`` (camelCase report
data), and falls back to using the list index as a string key.
"""
lookup: Dict[str, Dict[str, Any]] = {}
for i, group in enumerate(groups):
for key_field in ("group_hash", "group_id", "groupHash"):
key = group.get(key_field)
if key:
lookup[key] = group
# Also index by list position (string)
lookup[str(i)] = group
return lookup
def _resolve_underlying_groups(
consolidated_group: Dict[str, Any],
grouped_lookup: Dict[str, Dict[str, Any]],
) -> List[Dict[str, Any]]:
"""Resolve ``underlying_group_ids`` to actual group dicts.
Falls back to ``underlying_group_indices`` if ID resolution fails.
Returns the resolved list (may be empty if resolution is impossible).
"""
resolved: List[Dict[str, Any]] = []
# Try underlying_group_ids first
underlying_ids = consolidated_group.get("underlying_group_ids", [])
for uid in underlying_ids:
grp = grouped_lookup.get(uid)
if grp is not None:
resolved.append(grp)
# If ID resolution yielded nothing, try index-based
if not resolved:
underlying_indices = consolidated_group.get("underlying_group_indices", [])
for idx in underlying_indices:
grp = grouped_lookup.get(str(idx))
if grp is not None:
resolved.append(grp)
return resolved
def _expand_consolidated_into_groups(
consolidated_groups: List[Dict[str, Any]],
raw_groups: List[Dict[str, Any]],
) -> Tuple[List[Dict[str, Any]], Dict[str, Dict[str, Any]]]:
"""Expand consolidated groups into underlying group dicts for rendering.
Returns:
(expanded_groups, umbrella_map)
- expanded_groups: flat list of underlying group dicts (post
``_build_group_data()``) with consolidated metadata attached.
- umbrella_map: maps underlying group hash to its consolidated
group metadata (title, description, consolidated_id).
Used by the template to render umbrella banners.
"""
grouped_lookup = _build_grouped_lookup(raw_groups)
expanded: List[Dict[str, Any]] = []
umbrella_map: Dict[str, Dict[str, Any]] = {}
seen_group_hashes: set = set()
for cg in consolidated_groups:
resolved = _resolve_underlying_groups(cg, grouped_lookup)
consolidated_meta = {
"consolidatedId": cg.get("consolidated_id", ""),
"consolidatedTitle": cg.get("title", ""),
"consolidatedDescription": cg.get("description", ""),
"consolidatedImportance": cg.get("importance", ""),
"consolidatedType": cg.get("type", ""),
"isSingleton": cg.get("is_singleton", False),
"displayIndex": cg.get("display_index", 0),
"reasoning": cg.get("reasoning", ""),
}
if not resolved:
# Cannot resolve underlying groups - create a flat card from
# consolidated data directly
flat_group = {
"theme": cg.get("title", "Consolidated Suggestion"),
"category": cg.get("type", "unknown"),
"models": [],
"validation_status": "",
"suggestions": [{
"title": cg.get("title", ""),
"desc": cg.get("description", ""),
"importance": cg.get("importance", "MEDIUM"),
"type": cg.get("type", "modification"),
"reference": cg.get("reference", ""),
"source_model": "consolidated",
}],
"_consolidated_meta": consolidated_meta,
"_is_consolidated_flat": True,
}
expanded.append(flat_group)
else:
# Tag each resolved group with consolidated metadata.
# Use shallow copies to avoid mutating the original group dicts
# from raw_groups (which are shared references via the lookup).
first_in_umbrella = True
for grp in resolved:
grp_hash = grp.get("group_hash", grp.get("group_id", ""))
if grp_hash and grp_hash in seen_group_hashes:
continue
if grp_hash:
seen_group_hashes.add(grp_hash)
# Shallow copy before attaching metadata so callers'
# original group dicts are not mutated.
grp_copy = {**grp}
grp_copy["_consolidated_meta"] = consolidated_meta
if first_in_umbrella:
grp_copy["_umbrella_first"] = True
first_in_umbrella = False
# Map group hash to umbrella info for template rendering
if grp_hash:
umbrella_map[grp_hash] = consolidated_meta
expanded.append(grp_copy)
return expanded, umbrella_map
def _load_data_source(
phase_dir: Path,
data_source: str,
groups: List[Dict[str, Any]],
) -> Tuple[List[Dict[str, Any]], Optional[Dict[str, Dict[str, Any]]], List[Dict[str, str]]]:
"""Determine and load the data source for report generation.
Args:
phase_dir: Phase directory containing grouped.json / consolidated.json
data_source: ``"auto"``, ``"consolidated"``, or ``"grouped"``
groups: The groups already passed by the caller (from grouped.json)
Returns:
(effective_groups, umbrella_map, notices)
- effective_groups: The groups to render (may be expanded from consolidated)
- umbrella_map: Mapping of group hash -> consolidated metadata, or None
- notices: List of notice dicts ``{"type": ..., "message": ...}``
"""
notices: List[Dict[str, str]] = []
if data_source == "grouped":
return groups, None, notices
consolidated_path = phase_dir / "consolidated.json"
if data_source == "consolidated":
if not consolidated_path.exists():
raise FileNotFoundError(
f"consolidated.json not found at {consolidated_path}"
)
cons_groups, _meta = _load_consolidated_groups(consolidated_path)
if cons_groups is None:
raise ValueError(
f"consolidated.json at {consolidated_path} is malformed"
)
expanded, umbrella_map = _expand_consolidated_into_groups(
cons_groups, groups
)
return expanded, umbrella_map, notices
# data_source == "auto"
if consolidated_path.exists():
cons_groups, _meta = _load_consolidated_groups(consolidated_path)
if cons_groups is not None:
expanded, umbrella_map = _expand_consolidated_into_groups(
cons_groups, groups
)
return expanded, umbrella_map, notices
else:
# Malformed consolidated.json - fall back
notices.append({
"type": "warning",
"message": (
"Report generated from grouped data \u2014 "
"consolidated data was unavailable"
),
})
return groups, None, notices
# No consolidated.json - use grouped data
return groups, None, notices
def _parse_tasks_markdown(content: str) -> Dict[str, Any]:
"""Parse a tasks.md markdown file into a metadata dict keyed by task ref.
The tasks.md format uses headers like ``### Task T001: Create base config``
followed by metadata lines (Dependencies, Files, Complexity) and body text.
Returns a dict mapping the full section ref (e.g.
``"### Task T001: Create base config"``) to a metadata dict with keys:
``task_id``, ``title``, ``dependencies``, ``files``, ``complexity``,
``description``.
"""
# Match task headers: ## Task T001: ... or ### Task T001: ...
header_pattern = re.compile(
r'^(#{2,3}\s+(?:Task\s+)?T\d+[^:\n]*(?::\s*.*)?)', re.MULTILINE
)
headers = list(header_pattern.finditer(content))
if not headers:
return {}
result: Dict[str, Any] = {}
for i, match in enumerate(headers):
header_text = match.group(1).strip()
start = match.end()
end = headers[i + 1].start() if i + 1 < len(headers) else len(content)
body = content[start:end].strip()
# Extract task ID (e.g. "T001")
tid_match = re.search(r'(T\d+)', header_text)
task_id = tid_match.group(1) if tid_match else ""
# Extract title (text after "Task T001:" or "T001:")
title_match = re.search(r'T\d+[^:]*:\s*(.*)', header_text)
title = title_match.group(1).strip() if title_match else header_text
# Extract structured metadata from body lines
deps = ""
files = ""
complexity = ""
desc_lines = []
for line in body.splitlines():
stripped = line.strip()
if stripped.lower().startswith("**dependencies**"):
deps = re.sub(r'\*\*Dependencies\*\*\s*:\s*', '', stripped, flags=re.IGNORECASE).strip()
elif stripped.lower().startswith("**files"):
files = re.sub(r'\*\*Files[^*]*\*\*\s*:\s*', '', stripped, flags=re.IGNORECASE).strip()
elif stripped.lower().startswith("**complexity**"):
complexity = re.sub(r'\*\*Complexity\*\*\s*:\s*', '', stripped, flags=re.IGNORECASE).strip()
elif stripped and not stripped.startswith("---"):
desc_lines.append(stripped)
meta: Dict[str, Any] = {
"task_id": task_id,
"title": title,
"dependencies": deps,
"files": files,
"complexity": complexity,
"description": "\n".join(desc_lines[:5]), # First 5 lines
}
# Key by the full header text to match sectionRef values
result[header_text] = meta
# Also key by bare task ID for fallback matching
if task_id:
result[task_id] = meta
return result
# ---------------------------------------------------------------------------
# Scope tags
# ---------------------------------------------------------------------------
#: The consolidated page's persisted payload, decision regeneration's input
#: (as ``report_data.json`` is report.html's). Its name holds ``consolidated``
#: and ``report_data``, which every reaggregation scan's exclusions match.
CONSOLIDATED_REPORT_DATA = "consolidated_report_data.json"
#: The consolidated page itself.
CONSOLIDATED_REPORT_HTML = "consolidated-report.html"
#: The flat/PR payload's group views. A current payload's buckets name their
#: groups by index into ``groups`` (utils/report_view.py); a sidecar written
#: before that holds group copies in each bucket's ``suggestions``, so an
#: overlay must reach them as well as ``groups``.
_GROUP_VIEWS = ("fileView", "sectionView", "taskView")
def _payload_groups(report_data: Mapping[str, Any]) -> List[Dict[str, Any]]:
"""Every group dict of a flat/PR payload: ``groups`` and any view copies."""
found: List[Dict[str, Any]] = [g for g in report_data.get("groups") or [] if isinstance(g, dict)]
for view in _GROUP_VIEWS:
for bucket in (report_data.get(view) or {}).values():
if isinstance(bucket, dict):
found.extend(g for g in bucket.get("suggestions") or [] if isinstance(g, dict))
return found
def _scope_counts(groups_data: Sequence[Mapping[str, Any]]) -> Dict[str, int]:
"""Tag counts over distinct groups (never per suggestion or per view copy)."""
return _scope_report.count_entries(
(str(g.get("groupHash") or ""), g.get(_scope_report.ENTRY_KEY) or {})
for g in groups_data
)
def _scope_umbrellas(groups: Sequence[Dict[str, Any]],
copies: Sequence[Dict[str, Any]] = (),
umbrella_map: Optional[Dict[str, Any]] = None) -> None:
"""Give each umbrella's metadata its derived scope (in place).
The umbrella's tag comes from its underlying groups' validated entries
(``scope_report.umbrella_scope``); it is written onto every copy of that
umbrella's ``_consolidatedMeta`` in *groups* and *copies* and onto its
``umbrellaMap`` entries, so each view shows the same tag.
"""
members: Dict[str, List[Tuple[str, Mapping[str, Any]]]] = {}
for group in groups:
meta = group.get("_consolidatedMeta")
if not isinstance(meta, dict):
continue
key = str(meta.get("consolidatedId") or "")
label = str(group.get("displayLabel") or f"G{group.get('originalIndex', '')}")
members.setdefault(key, []).append((label, group.get(_scope_report.ENTRY_KEY) or {}))
umbrellas = {key: _scope_report.umbrella_scope(found) for key, found in members.items()}
for group in list(groups) + list(copies):
meta = group.get("_consolidatedMeta")
if isinstance(meta, dict) and str(meta.get("consolidatedId") or "") in umbrellas:
meta[_scope_report.ENTRY_KEY] = umbrellas[str(meta.get("consolidatedId") or "")]
for meta in (umbrella_map or {}).values():
if isinstance(meta, dict) and str(meta.get("consolidatedId") or "") in umbrellas:
meta[_scope_report.ENTRY_KEY] = umbrellas[str(meta.get("consolidatedId") or "")]
def _persisted_round(report_data: Mapping[str, Any],
scope_state: Optional[Mapping[str, Any]]) -> Optional[Dict[str, Any]]:
"""The round to overlay: ``state.json``'s record, else the payload's own.
``None`` when neither exists (a legacy payload with no recorded round):
there is nothing to recompute and the page keeps rendering unknown tags.
"""
info = _scope_report.round_info(scope_state or {}, str(report_data.get("phase") or ""))
block = report_data.get(_scope_report.REPORT_KEY)
if info["recorded"]:
if not info.get("baseline") and isinstance(block, Mapping):
info["baseline"] = block.get("baseline")
return info
if not isinstance(block, Mapping):
return None
return {
"recorded": bool(block.get("recorded")),
"reviewPolicy": block.get("reviewPolicy"),
"reviewPolicySource": block.get("reviewPolicySource"),
"applyPolicy": block.get("applyPolicy"),
"applyPolicySource": block.get("applyPolicySource"),
"effectivePolicy": block.get("effectivePolicy"),
"baselineId": block.get("baselineId"),
"baseline": block.get("baseline"),
"deferrals": [],
}
def _missing_entry() -> Dict[str, Any]:
"""A legacy group's scope entry: never classified."""
return {
"relation": "unclear", "label": _scope_report.sp.LABELS["unclear"],
"reason": "no validated scope classification", "reference": "",
"authority": "missing", "validated": False, "stale": False, "provisional": False,
}
def _rescope(group: Dict[str, Any], info: Mapping[str, Any],
deferrals: Mapping[str, Mapping[str, Any]]) -> None:
"""Recompute *group*'s scope eligibility for the round's policy (in place).
The classification (relation, reason, authority, binding) is the one
persisted at review time and is never changed; only the decision is
asked again of the one gate (``scope_report.replay_decision``).
"""
entry = group.get(_scope_report.ENTRY_KEY)
entry = dict(entry) if isinstance(entry, Mapping) else _missing_entry()
entry["decision"] = _scope_report.replay_decision(
entry, info.get("effectivePolicy"), deferrals.get(str(group.get("groupHash") or "")))
group[_scope_report.ENTRY_KEY] = entry
def _overlay_scope(report_data: Dict[str, Any], scope_state: Optional[Mapping[str, Any]]) -> bool:
"""Recompute a flat/PR payload's scope eligibility from the recorded round.
Uses the persisted payload and ``state.json``'s ``scope_policy`` record
only — never the live plan or a model. Returns whether anything shown
changed (the effective policy, or any group's outcome).
"""
info = _persisted_round(report_data, scope_state)
if info is None:
return False
before = json.dumps([_scope_view(g) for g in report_data.get("groups") or []]
+ [report_data.get(_scope_report.REPORT_KEY)], sort_keys=True, default=str)
deferrals = _scope_report.deferral_index(info)
groups = [g for g in report_data.get("groups") or [] if isinstance(g, dict)]
own = {id(g) for g in groups}
copies = [g for g in _payload_groups(report_data) if id(g) not in own]
for group in groups + copies:
_rescope(group, info, deferrals)
_scope_umbrellas(groups, copies, report_data.get("umbrellaMap"))
report_data[_scope_report.REPORT_KEY] = _scope_report.report_block(info, _scope_counts(groups))
after = json.dumps([_scope_view(g) for g in groups]
+ [report_data.get(_scope_report.REPORT_KEY)], sort_keys=True, default=str)
return before != after
def _scope_view(group: Any) -> Any:
return (group or {}).get(_scope_report.ENTRY_KEY) if isinstance(group, Mapping) else None
def generate_html_report(
groups: List[Dict[str, Any]],
plan_path: Path,
phase_dir: Path,
phase_type: str,
models: List[str],
failed_models: Optional[Dict[str, str]] = None,
validation_results: Optional[List[Dict[str, Any]]] = None,
base_ref: Optional[str] = None,
tasks_path: Optional[Path] = None,
template_style: str = 'pr',
diff_data: Optional[Dict] = None,
data_source: str = 'auto',
file_snapshots: Optional[Dict[str, list]] = None,
served_models: Optional[Dict[str, Dict[str, Any]]] = None,
usage: Optional[Dict[str, Dict[str, Any]]] = None,
commit_review: Optional[Mapping[str, Any]] = None,
requested_models: Optional[int] = None,
salvage_requested: Optional[Sequence[str]] = None,
head_ref: Optional[str] = None,
repo_root: Optional[str] = None,
file_labels: Optional[Dict[str, str]] = None,
scope_state: Optional[Mapping[str, Any]] = None,
) -> str:
"""Generate complete HTML report and return the HTML string.
The page is the view (``report_view.build_report_view``, these
parameters as ``ReportInputs``) with its views indexed
(``report_view.compact_views``), embedded in the style's template; the
same payload is persisted as ``report_data.json``. A missing template
returns an error page and writes no sidecar.
Args:
groups: Validated groups from grouped.json
plan_path: Path to the original plan file
phase_dir: Directory for this phase (for log files)
phase_type: Phase identifier ("review-plan", "code-review", "review-tasks")
models: List of models that were used
failed_models: Optional dict of model name -> error message for
failures. Written out as ``reportData.failedModels`` (always a
dict; the templates iterate it with ``Object.keys``), and, when
non-empty, as one ``warning`` notice whose ``message`` is
:func:`failed_models_line` without its bold markers — the same
text as ``report.md``'s ``**Models failed:**`` line.
requested_models: The size of the run's requested model set, written
out as ``reportData.requestedModels`` and used for the notice's
"N of M requested". The caller's own count (the fan-out's
``len(model_specs)``, a reaggregate's recorded requested set) —
never succeeded plus failed. ``None`` leaves the key out, and the
page then names the failures without "of M".
salvage_requested: The failed specs whose entry carries the salvage
clause, exactly as the caller passed them to the markdown line.
validation_results: Optional list of validation results
base_ref: Optional git ref to diff against for PR-style code context.
When provided (and ``diff_data`` is ``None``), ``capture_diff_hunks()``
is called to obtain structured diff data for files referenced by
suggestions.
tasks_path: Optional path to a tasks JSON file. When provided, task
metadata is loaded and passed to ``build_task_view()``.
template_style: Template to use — ``'pr'`` selects
``pr_report_template.html`` (default), ``'flat'`` selects the
original ``report_template.html``.
diff_data: Optional pre-computed diff hunk data (as returned by
``capture_diff_hunks()``). When provided, it is used directly as
``reportData.diffData``, bypassing ``base_ref``-driven capture.
This allows callers like ``reaggregate_from_existing_files()`` to
inject cached diff data without re-running the git operation.
data_source: Data source strategy — ``"auto"`` (default) checks for
``consolidated.json`` first, falls back to ``grouped.json``;
``"consolidated"`` uses ``consolidated.json`` directly (raises
if missing); ``"grouped"`` uses ``grouped.json`` directly.
file_snapshots: Optional dict mapping file paths to pre-captured
line lists (as returned by ``capture_file_snapshots()``). When
provided, ``capture_file_context()`` uses these snapshots instead
of reading files from disk, ensuring the report reflects file
state at review start rather than at report-generation time.
served_models: Optional attribution, ``{model_spec: {"served_model":
str, "fallback": bool}}``. Only ever non-empty when a
``fallback_models`` list is configured; an entry labels that model's
badge with the model that actually served the turn and adds
``reportData.servedModels``. Omitted (the shipped default) leaves
``report_data.json`` and the embedded data exactly as they were.
usage: Optional per-model usage, ``{model_spec: {"input_tokens", ...,
"cost_usd", "tool_uses"}}``, as the fan-out recorded it in
``.status.json``. Non-empty only for adapters that report usage at
all (``usage_support`` above ``none``) — a model with no entry gets
no ``usage`` key on its metadata and no clause on its badge, which
is what keeps a duration-only adapter from being reported as a free
run. Adds ``reportData.usageTotal`` (the columnwise sum over the
models that reported) and its rendered label.
commit_review: A commit review's report payload
(``utils.commit_report.report_payload``): stored as
``reportData.commitRange`` with the attribution
per group, so the header's commit block, the commit filter, the
"Introduced by" lines, the drift badges and the export help's
apply command render from ``report_data.json`` alone (a
regenerated report calls no git). ``None`` adds nothing.
head_ref: The commit a pinned review ends at (``review-code
--head-ref``, a commit brief). The
diff hunks are then ``capture_diff_hunks(base_ref, files,
head_ref, cwd=repo_root)`` — two commits, no "uncommitted changes"
notice — the snapshots default to the files as that commit holds
them (``capture_file_snapshots_at``), and the context chain never
reads the disk for a file missing from the snapshots (a path absent
at ``head``): the diff data (a deleted file's
``last_known_content``), then ``anchor_text``, then nothing, so a
file recreated on disk since ``head`` never shows working-tree
bytes as the reviewed code. ``None`` keeps today's chain.
repo_root: Where those git reads run (the paths are root-relative).
file_labels: ``{path: label}`` for the paths absent at ``head``
(``deleted in <range>``, ``renamed to <new> in <range>``, ``absent
at <head7>``), carried on the file's ``fileContexts`` entry as
``label``, the same words the validation excerpt's header uses.
scope_state: The ``state.json`` dict whose ``scope_policy`` record
holds this review round's policy, baseline and deferrals; ``None``
reads ``state.json`` beside *phase_dir*. Every group gains
``scope`` (its validated tag and the effective policy's outcome),
every suggestion its provisional ``scope``, every umbrella a
derived one, and the payload ``scopePolicy``. A legacy
round reads ``expand`` and ``Scope unclear``.
Returns:
Complete HTML string for the report
Raises:
FileNotFoundError: When ``data_source="consolidated"`` and the file
does not exist.
ValueError: When ``data_source`` is not one of the allowed values,
or when ``data_source="consolidated"`` and the file is malformed,
or when the template has no data placeholder.
"""
# ``report_view`` imports this module: a load-time cycle.
from .report_view import ReportInputs, build_report_view, compact_views
view = build_report_view(ReportInputs(
groups=groups, plan_path=plan_path, phase_dir=phase_dir, phase_type=phase_type,
models=models, failed_models=failed_models, validation_results=validation_results,
base_ref=base_ref, tasks_path=tasks_path, template_style=template_style,
diff_data=diff_data, data_source=data_source, file_snapshots=file_snapshots,
served_models=served_models, usage=usage, commit_review=commit_review,
requested_models=requested_models, salvage_requested=salvage_requested,
head_ref=head_ref, repo_root=repo_root, file_labels=file_labels,
scope_state=scope_state,
))
# Each group once: the views name theirs by index (utils/report_view.py).
payload = compact_views(view)
try:
html = embed_report_data(payload, load_report_template(template_style))
except FileNotFoundError as exc:
# The template or a file it inlines (templates/shared/).
return _missing_template_page(exc.filename)
# Persist the assembled report_data so the apply phase can overlay human
# decisions onto it and re-embed without reconstructing runtime inputs
# (diff_data, base_ref, models, ...). Best-effort: never fail report
# generation if the sidecar cannot be written.
try:
_write_atomic(Path(phase_dir) / "report_data.json", sidecar_json(payload))
except OSError:
pass
return html
#: ``report_data.json``'s key for a commit review's payload.
COMMIT_RANGE_KEY = "commitRange"
#: The apply commands the flat report's export help names for a plan's review
#: (every review phase shares that template). A commit review passes its own
#: list (``commitRange.applyCommands``) instead.
DEFAULT_APPLY_COMMANDS: Tuple[str, ...] = (
"apply-suggestions", "apply-code-fixes", "apply-task-suggestions",
)
#: The label the flat report's header gives the anchor document of a plan's
#: review; a commit review passes ``commitRange.documentLabel``.
DEFAULT_DOCUMENT_LABEL = "Plan"
#: Template slots the generator fills before the data goes in. Each is an
#: HTML comment, so a template read without the generator renders nothing.
SLOT_DOCUMENT_LABEL = "<!--MLLM:document-label-->"
SLOT_APPLY_COMMANDS = "<!--MLLM:apply-commands-->"
SLOT_EXPORT_HELP = "<!--MLLM:export-help-->"
#: Where every report page (flat, PR and consolidated) receives the vendored
#: markdown libraries, inlined: a report is one self-contained file that loads
#: nothing from the network. Without them, the pages' ``renderMarkdown`` (in
#: ``templates/shared/report_core.js``) escapes model text instead of rendering it.
SLOT_VENDOR_SCRIPTS = "<!--MLLM:vendor-scripts-->"
_VENDOR_DIR = Path(__file__).parent.parent / "templates" / "vendor"
#: ``(file under templates/vendor/, npm package, version, sha256 of the file)``,
#: in load order. Each file is its npm tarball's own bytes, unmodified. A file
#: whose digest differs is not inlined, so the page escapes rather than run
#: unpinned code. Update steps: docs/development.md#vendored-report-scripts.
VENDORED_SCRIPTS: Tuple[Tuple[str, str, str, str], ...] = (
("marked.umd.js", "marked", "18.1.1",
"b82b9334406d8bdd16b6236c08de1cb65b2a859873ca9503d9cc0b292ca3c12a"),
("purify.min.js", "dompurify", "3.4.17",
"cd37898f9782adf54820c413191b5691803f0f137c799d6edcfd38523b4c2c31"),
)
#: A tag the HTML tokenizer would act on inside an inline script: ``</script``
#: ends it early, and ``<script`` after ``<!--`` stops ``</script>`` ending it.
_SCRIPT_TAG = re.compile(r"</?script", re.IGNORECASE)
#: The bundles' trailing source-map comment; the maps are not vendored.
_SOURCE_MAP_LINE = re.compile(r"\n//# sourceMappingURL=[^\n]*\s*\Z")
def _vendored_script(filename: str, package: str, version: str, sha256: str) -> str:
"""One vendored library as an inline ``<script>``, or ``""`` (with a
warning) when the file is missing, differs from its pin or cannot be
inlined safely."""
path = _VENDOR_DIR / filename
try:
raw = path.read_bytes()
except OSError as exc:
logger.warning("report script %s@%s not inlined: %s", package, version, exc)
return ""
digest = hashlib.sha256(raw).hexdigest()
if digest != sha256:
logger.warning("report script %s@%s not inlined: %s has sha256 %s, pinned %s",
package, version, path, digest, sha256)
return ""
text = _SOURCE_MAP_LINE.sub("\n", raw.decode("utf-8"))
if _SCRIPT_TAG.search(text):
logger.warning("report script %s@%s not inlined: it holds a script tag", package, version)
return ""
return f'<script data-vendored="{package}@{version}">\n{text}</script>'
_vendor_scripts_cache: Optional[str] = None
def vendor_scripts_html() -> str:
"""The inline ``<script>`` blocks for :data:`SLOT_VENDOR_SCRIPTS`."""
global _vendor_scripts_cache
if _vendor_scripts_cache is None:
_vendor_scripts_cache = "\n".join(
block for block in (_vendored_script(*entry) for entry in VENDORED_SCRIPTS) if block)
return _vendor_scripts_cache
#: Where every report page receives the code the three pages share, inlined
#: from ``templates/shared/``: its styles before the page's own ``<style>``
#: (so the page's rules win a tie), its script after the vendored libraries
#: and before the page's own ``<script>``. See
#: docs/development.md#shared-report-code.
SLOT_CORE_STYLE = "<!--MLLM:report-core-style-->"
SLOT_CORE_SCRIPT = "<!--MLLM:report-core-script-->"
_SHARED_DIR = Path(__file__).parent.parent / "templates" / "shared"
#: ``slot: (file under templates/shared/, element)``.
SHARED_ASSETS: Dict[str, Tuple[str, str]] = {
SLOT_CORE_STYLE: ("report_core.css", "style"),
SLOT_CORE_SCRIPT: ("report_core.js", "script"),
}
#: What a shared file may not hold: a tag the HTML tokenizer would act on
#: inside its element (``</script``, ``<script``, ``</style``), a comment
#: opener (``<!--``, which every slot starts with), or the data placeholder.
_SHARED_FORBIDDEN = re.compile(r"</?script|</style|<!--|REPORT_DATA_PLACEHOLDER", re.IGNORECASE)
def shared_asset_html(slot: str) -> str:
"""The inline element for one of :data:`SHARED_ASSETS`' slots.
The pages cannot run without it, so a missing file is a
``FileNotFoundError`` (``filename`` set), as a missing template is, and a
file holding what :data:`_SHARED_FORBIDDEN` names is a ``ValueError``."""
filename, element = SHARED_ASSETS[slot]
path = _SHARED_DIR / filename
try:
text = path.read_text(encoding="utf-8")
except FileNotFoundError:
missing = FileNotFoundError(f"Report template file not found: {path}")
missing.filename = str(path)
raise missing from None
found = _SHARED_FORBIDDEN.search(text)
if found:
raise ValueError(f"{path} cannot be inlined: it holds {found.group(0)!r}")
return f'<{element} data-shared="{filename}">\n{text}</{element}>'
def inline_shared_slots(template: str) -> str:
"""*template* with the slots that take no report data filled: the shared
style and script (:func:`shared_asset_html`) and the vendored libraries
(:func:`vendor_scripts_html`). The text a page's script sees, data aside."""
for slot in SHARED_ASSETS:
if slot in template:
template = template.replace(slot, shared_asset_html(slot))
if SLOT_VENDOR_SCRIPTS in template:
template = template.replace(SLOT_VENDOR_SCRIPTS, vendor_scripts_html())
return template
def commit_range_report_data(
commit_review: Mapping[str, Any], groups_data: List[Dict[str, Any]]
) -> Dict[str, Any]:
"""``reportData.commitRange``: the payload plus the attribution per group
(``{groupHash: {introducedBy, source}}``). Each group's data also gains
the attributed commit's short SHA and subject, read from the payload's
``commits`` (every commit of the range), never from git."""
subjects = {
str(c.get("sha")): c for c in commit_review.get("commits") or ()
if isinstance(c, Mapping)
}
attribution: Dict[str, Dict[str, Any]] = {}
for group in groups_data:
if "introducedBySource" not in group:
continue
sha = group.get("introducedBy")
if sha:
group["introducedByShort"] = str(sha)[:7]
group["introducedBySubject"] = str((subjects.get(sha) or {}).get("subject") or "")
if group.get("groupHash"):
attribution[str(group["groupHash"])] = {
"introducedBy": sha, "source": group.get("introducedBySource"),
}
data = dict(commit_review)
data["attribution"] = attribution
return data
def _join_commands(commands: Sequence[str]) -> str:
"""``a``, ``a or b``, ``a, b, or c``: the export help's wording."""
items = [str(c) for c in commands if c]
if len(items) <= 1:
return items[0] if items else ""
if len(items) == 2:
return f"{items[0]} or {items[1]}"
return ", ".join(items[:-1]) + f", or {items[-1]}"
def _fill_template_slots(template: str, report_data: Mapping[str, Any]) -> str:
"""Fill the slots that take no data (:func:`inline_shared_slots`: the
shared style and script, the vendored libraries), then the label and
export-help slots from *report_data*. The fixed text goes in first, so no
text derived from the data is ever searched for a slot.
A plan's review gets exactly the text the templates used to carry
(``Plan:``, the three apply commands, no PR-template help); a commit
review gets ``Commit brief:`` and its own apply command, from the payload
the generator stored, so a regenerated report says the same."""
# Imported here: `util report` does not otherwise load html.
import html as _html
template = inline_shared_slots(template)
commit = report_data.get(COMMIT_RANGE_KEY)
commit = commit if isinstance(commit, Mapping) else None
label = (commit or {}).get("documentLabel") or DEFAULT_DOCUMENT_LABEL
commands = list((commit or {}).get("applyCommands") or DEFAULT_APPLY_COMMANDS)
joined = _html.escape(_join_commands(commands), quote=False)
help_html = ""
if commit:
help_html = (
'<span class="export-help" id="export-help">Export saves '
'<code>user_selections.json</code>: put it next to <code>report.md</code>, '
f'then run <code>{joined}</code> to apply what you kept.</span>'
)
return (
template
.replace(SLOT_DOCUMENT_LABEL, _html.escape(f"{label}:", quote=False))
.replace(SLOT_APPLY_COMMANDS, joined)
.replace(SLOT_EXPORT_HELP, help_html)
)
def script_json(report_data: Any) -> str:
"""*report_data* as JSON safe inside an inline ``<script>``.
Escapes the sequences that would break out of the surrounding tag:
``</script>`` (``</`` in general) and ``<!--`` (an HTML comment opener
inside JS). ``\\/`` is valid JSON (RFC 8259). Every report page —
flat, PR and consolidated — embeds its payload through this.
"""
return (
json.dumps(report_data, indent=2)
.replace("</", "<\\/")
.replace("<!--", "<\\!--")
)
def sidecar_json(report_data: Any) -> str:
"""A report sidecar's text (``report_data.json``,
``consolidated_report_data.json``): compact JSON. Machines read it; the
page is where a person reads the data."""
return json.dumps(report_data, separators=(",", ":"))
#: Where a template takes its data, longest spelling first: the shipped
#: templates write ``const reportData = /* REPORT_DATA_PLACEHOLDER */null;``.
_DATA_PLACEHOLDERS = ("/* REPORT_DATA_PLACEHOLDER */null", "/* REPORT_DATA_PLACEHOLDER */",
"REPORT_DATA_PLACEHOLDER")
def embed_report_data(report_data: Mapping[str, Any], template: str) -> str:
"""Every report page (flat, PR, consolidated): *report_data* embedded in
*template* at its data placeholder.
Shared by initial generation and post-apply regeneration so every path
escapes (:func:`script_json`) and injects the data identically. The
template's slots (:func:`_fill_template_slots`: the shared code, the
vendored scripts, the labels) are filled first, before any data is in it,
so text inside the data can never be taken for a slot. A template without the placeholder is
an error (``ValueError``) rather than a page with no data.
"""
template = _fill_template_slots(template, report_data)
for placeholder in _DATA_PLACEHOLDERS:
if placeholder in template:
return template.replace(placeholder, script_json(report_data))
raise ValueError(
"Template does not contain REPORT_DATA_PLACEHOLDER \u2014 "
"cannot inject report data."
)
def write_html_report(html: str, phase_dir: Path) -> Path:
"""Write HTML report to the phase directory.
Args:
html: The complete HTML content to write
phase_dir: Directory to write the report to
Returns:
Path to the written report file
"""
phase_dir.mkdir(parents=True, exist_ok=True)
report_path = phase_dir / "report.html"
_write_atomic(report_path, html)
return report_path
# ---------------------------------------------------------------------------
# PR-style view index builders
# ---------------------------------------------------------------------------
def _extract_file_path(file_ref: str) -> str:
"""Extract the file path from a fileRef string, stripping line ranges.
Examples:
"src/auth/login.py:43-50" -> "src/auth/login.py"
"src/auth/login.py:43" -> "src/auth/login.py"
"src/auth/login.py" -> "src/auth/login.py"
"" -> ""
"""
if not file_ref:
return ""
# Strip trailing :line or :line-line
idx = file_ref.rfind(":")
if idx > 0:
after_colon = file_ref[idx + 1:]
# Only strip if the part after the colon looks like a line range
if after_colon and all(c in "0123456789-" for c in after_colon):
return file_ref[:idx]
return file_ref
def _get_group_file_path(group: Dict[str, Any]) -> str:
"""Determine the primary file path for a group.
Uses the first non-empty ``fileRef`` among the group's suggestions.
Returns ``""`` if no suggestion has a ``fileRef``.
"""
for suggestion in group.get("suggestions", []):
file_ref = suggestion.get("fileRef", "")
if file_ref:
return _extract_file_path(file_ref)
return ""
#: A reviewer that cites two places writes one composite reference —
#: ``"## Design Requirements / ### 7. Lap Integration"``, occasionally
#: comma-joined. Split on a *delimited* separator only: a bare slash is part
#: of a heading (``### 5. Visual/Audio Effects (Juice)``) and splitting there
#: would invent two sections that the plan does not have.
_SECTION_REF_SEPARATOR = re.compile(r"\s+/\s+|,\s+")
def split_section_refs(section_ref: str) -> List[str]:
"""Split a composite section reference into the sections it names.
``"## Design Requirements / ### 7. Lap Integration"`` names two sections;
a plain ``"### 7. Lap Integration"`` names one. Order is preserved and
repeats are dropped, so a reference can be used directly as a bucket key
list.
"""
if not section_ref:
return []
refs: List[str] = []
seen: Set[str] = set()
for part in _SECTION_REF_SEPARATOR.split(str(section_ref)):
part = part.strip()
if part and part not in seen:
seen.add(part)
refs.append(part)
return refs
def _get_group_section_refs(group: Dict[str, Any]) -> List[str]:
"""Every section a group's suggestions cite, deduped, in first-seen order.
A group is counted under *each* section it names rather than under the
whole reference string. Bucketing by the raw string made every composite
reference its own bucket — a real 8-section plan review rendered 23
section buckets, and the section a composite named second was invisible
in the one that carried its name.
Returns ``[]`` if no suggestion has a ``sectionRef``.
"""
refs: List[str] = []
seen: Set[str] = set()
for suggestion in group.get("suggestions", []):
for ref in split_section_refs(suggestion.get("sectionRef", "")):
if ref not in seen:
seen.add(ref)
refs.append(ref)
return refs
def _get_group_task_refs(group: Dict[str, Any]) -> List[str]:
"""Every task a group's suggestions cite, deduped, in first-seen order.
Task review stores the task ID in the ``sectionRef`` / ``reference``
field (which maps to ``sectionRef`` in camelCase report data), and a
suggestion that spans two tasks writes both. Returns ``[]`` if no
suggestion has a ``sectionRef``.
"""
return _get_group_section_refs(group)
def _collect_all_suggestions(groups: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
"""Flatten all suggestions from a list of groups into a single list."""
result = []
for group in groups:
result.extend(group.get("suggestions", []))
return result
def _file_sort_key(file_path: str) -> tuple:
"""Sort key for file paths: directory first, then filename alphabetically.
Sorts by (directory, filename) so files in the same directory are
grouped together, and within each directory files are sorted
alphabetically. The ``_global`` key always sorts last.
"""
if file_path == "_global":
# Sort _global last
return ("\xff", "\xff")
parts = file_path.rsplit("/", 1)
if len(parts) == 2:
return (parts[0].lower(), parts[1].lower())
# No directory component — sort at root level
return ("", parts[0].lower())
def build_file_view(
groups: List[Dict[str, Any]],
) -> Dict[str, Any]:
"""Build a file-based index from the flat groups list.
Groups suggestions by ``fileRef`` file path for code-review PR view.
Suggestions with no ``fileRef`` are placed under the ``_global`` key.
Args:
groups: List of processed group dicts (post ``_build_group_data()``).
Returns:
Dict mapping file paths (and ``_global``) to::
{
"suggestions": [group, ...], # groups anchored to this file
"suggestionCount": int, # total individual suggestions
"maxImportance": str, # highest importance across all suggestions
}
Keys are sorted by directory then alphabetically, with ``_global`` last.
"""
file_buckets: Dict[str, List[Dict[str, Any]]] = {}
for group in groups:
file_path = _get_group_file_path(group)
key = file_path if file_path else "_global"
file_buckets.setdefault(key, []).append(group)
# Build the result dict with sorted keys
sorted_keys = sorted(file_buckets.keys(), key=_file_sort_key)
result: Dict[str, Any] = {}
for key in sorted_keys:
bucket_groups = file_buckets[key]
all_suggestions = _collect_all_suggestions(bucket_groups)
result[key] = {
"suggestions": bucket_groups,
"suggestionCount": len(all_suggestions),
"maxImportance": compute_max_importance(all_suggestions),
}
# Ensure _global key exists even if empty
if "_global" not in result:
result["_global"] = {
"suggestions": [],
"suggestionCount": 0,
"maxImportance": "",
}
return result
def build_section_view(
groups: List[Dict[str, Any]],
) -> Dict[str, Any]:
"""Build a section-based index from the flat groups list.
Groups suggestions by ``sectionRef`` for plan-review PR view. A composite
reference (``"## Overview / ### 7. Lap Integration"``) is split, and the
group is counted under **each** section it names — so a section's bucket
holds everything that cited it, however the citing reviewer spelled the
citation. Groups with no ``sectionRef`` are placed under the ``_global``
key.
A group naming two sections appears in two buckets, so the bucket counts
sum to more than the group count. That is the point: the view answers
"what did reviewers say about this section?", and a suggestion about two
sections is an answer for both.
Args:
groups: List of processed group dicts (post ``_build_group_data()``).
Returns:
Dict mapping section references (and ``_global``) to::
{
"suggestions": [group, ...], # groups anchored to this section
"suggestionCount": int, # total individual suggestions
"maxImportance": str, # highest importance across all suggestions
}
"""
section_buckets: Dict[str, List[Dict[str, Any]]] = {}
for group in groups:
for key in _get_group_section_refs(group) or ["_global"]:
section_buckets.setdefault(key, []).append(group)
result: Dict[str, Any] = {}
for key, bucket_groups in section_buckets.items():
all_suggestions = _collect_all_suggestions(bucket_groups)
result[key] = {
"suggestions": bucket_groups,
"suggestionCount": len(all_suggestions),
"maxImportance": compute_max_importance(all_suggestions),
}
return result
def build_task_view(
groups: List[Dict[str, Any]],
tasks_metadata: Optional[Dict[str, Any]] = None,
) -> Dict[str, Any]:
"""Build a task-based index from the flat groups list.
Groups suggestions by task ID (from the ``sectionRef`` / ``reference``
field) for task-review PR view. A composite reference naming more than
one task (``"T003 / T004"``, ``"T003, T004"``) is split and the group is
counted under each task it names. A reference that isn't a bare task
ID (``"Plan Coverage"``, or a plan section heading like
``"## 4.6 Timing & Checkpoints"`` — ``prompts/task_review.txt`` invites
either spelling for a coverage-gap finding) is routed to the
``_coverageGaps`` bucket instead of becoming its own phantom task — a
composite naming a non-task reference alongside a real task lands in
both. Groups with no reference at all go to the ``_unanchored`` bucket.
Args:
groups: List of processed group dicts (post ``_build_group_data()``).
tasks_metadata: Optional dict mapping task IDs (e.g. ``"T001"``)
to task metadata dicts. When ``None``, all ``taskMetadata``
values in the result are ``None``.
Returns:
Dict mapping task IDs (and ``_coverageGaps``, ``_unanchored``) to::
{
"taskMetadata": {...} | None,
"suggestions": [group, ...],
"suggestionCount": int,
"maxImportance": str,
}
The ``_coverageGaps`` entry contains groups whose reference is not
a bare task ID (``"Plan Coverage"`` or a plan section heading).
The ``_unanchored`` entry contains groups with no reference.
"""
task_buckets: Dict[str, List[Dict[str, Any]]] = {}
coverage_gaps: List[Dict[str, Any]] = []
unanchored: List[Dict[str, Any]] = []
for group in groups:
task_refs = _get_group_task_refs(group)
if not task_refs:
# Groups with no reference — unanchored findings
unanchored.append(group)
continue
for task_ref in task_refs:
# Anything that isn't a bare "T###" id is a coverage-gap
# reference, not a task — the prompt spells those either as
# the literal "Plan Coverage" or as a plan section heading
# (e.g. "## 4.6 Timing & Checkpoints"), and treating the
# literal string as the only such spelling turned every
# heading-style coverage gap into its own phantom task.
if not re.fullmatch(r'T\d+', task_ref):
coverage_gaps.append(group)
else:
task_buckets.setdefault(task_ref, []).append(group)
result: Dict[str, Any] = {}
for task_id, bucket_groups in task_buckets.items():
all_suggestions = _collect_all_suggestions(bucket_groups)
task_meta = None
if tasks_metadata is not None:
task_meta = tasks_metadata.get(task_id, None)
result[task_id] = {
"taskMetadata": task_meta,
"suggestions": bucket_groups,
"suggestionCount": len(all_suggestions),
"maxImportance": compute_max_importance(all_suggestions),
}
# Always include _coverageGaps
coverage_suggestions = _collect_all_suggestions(coverage_gaps)
result["_coverageGaps"] = {
"suggestions": coverage_gaps,
"suggestionCount": len(coverage_suggestions),
"maxImportance": compute_max_importance(coverage_suggestions),
}
# Always include _unanchored (groups with no reference)
unanchored_suggestions = _collect_all_suggestions(unanchored)
result["_unanchored"] = {
"suggestions": unanchored,
"suggestionCount": len(unanchored_suggestions),
"maxImportance": compute_max_importance(unanchored_suggestions),
}
return result
# ---------------------------------------------------------------------------
# Post-apply human-decision overlay
# ---------------------------------------------------------------------------
def _normalize_human_decision(record: Dict[str, Any]) -> Dict[str, Any]:
"""Normalize a state.json human-decision record for the report template.
Maps the recorded shape (``decision`` plus ``batch_context`` markers) into
the camelCase fields the template's ``getHumanDecisionInfo()`` reads,
collapsing everything to a single ``outcome`` of approved / salvaged /
skipped. A salvaged item is recorded with ``decision == "approved"`` and a
``judge_auto_decide_salvage`` marker, so the marker — not ``decision`` —
determines the outcome. A record in the ``claude_*`` spelling an earlier
version wrote is read through ``judge_vocab.canonical_value``, so it renders
the same and the sidecar it is written back to carries only the new names.
"""
bc = record.get("batch_context") or {}
decision_source = canonical_value(bc.get("decision_source"))
batch_action = canonical_value(bc.get("batch_action"))
source = decision_source or batch_action or "user"
decision = record.get("decision")
is_salvage = JUDGE_AUTO_DECIDE_SALVAGE in (decision_source, batch_action)
if is_salvage:
outcome = "salvaged"
elif decision == "approved":
outcome = "approved"
elif decision == "skipped":
outcome = "skipped"
else:
outcome = decision or "decided"
return {
"outcome": outcome,
"decision": decision,
JUDGE_DECIDED: str(source).startswith(JUDGE_AUTO_DECIDE),
"source": source,
"reason": record.get("reason", "") or "",
"salvagedDescription": bc.get("salvaged_description", "") or "",
"dropped": bc.get("dropped", "") or "",
"importanceAtDecision": bc.get("importance_at_decision", "") or "",
"judge": bc.get("judge", "") or "",
}
def _overlay_human_decisions(
report_data: Dict[str, Any],
human_decisions: Dict[str, Dict[str, Any]],
) -> int:
"""Attach normalized human decisions onto ``report_data`` groups in place.
Decisions are keyed by group_id (== ``group_hash``), matched against each
group's ``groupHash``. Returns the number of groups matched and stamps a
``humanDecisionsSummary`` onto ``report_data``.
The overlay is a **replacement**, not an accumulation: any stamp a previous
overlay left on a group that this decision map does not name is dropped
first. The sidecar is rewritten with what this function produced, so keeping
them would survive `--fresh` (which clears ``human_decisions_{phase}``) and
show two judging rounds' badges at once, under a
``humanDecisionsSummary`` that counted only the newer round.
"""
summary = {
"approved": 0,
"salvaged": 0,
"skipped": 0,
JUDGE_DECIDED: 0,
"total": 0,
}
matched = 0
for group in report_data.get("groups", []):
group_hash = group.get("groupHash")
group.pop("humanDecision", None)
if not group_hash or group_hash not in human_decisions:
continue
info = _normalize_human_decision(human_decisions[group_hash])
group["humanDecision"] = info
matched += 1
summary["total"] += 1
if info["outcome"] in summary:
summary[info["outcome"]] += 1
if info[JUDGE_DECIDED]:
summary[JUDGE_DECIDED] += 1
report_data["humanDecisionsSummary"] = summary
return matched
#: Each report page's template under ``templates/``, by style.
REPORT_TEMPLATES = {
"pr": "pr_report_template.html",
"flat": "report_template.html",
"consolidated": "consolidated_report_template.html",
}
def load_report_template(style: str) -> str:
"""The template text of a report page: ``pr``, ``consolidated``, or the
flat one for any other style. A missing PR template falls back to the
flat one with a warning. Raises ``FileNotFoundError`` (``filename`` set
to the path looked for) when the file is missing."""
templates_dir = Path(__file__).parent.parent / "templates"
path = templates_dir / REPORT_TEMPLATES.get(style, REPORT_TEMPLATES["flat"])
if style == "pr" and not path.exists():
warnings.warn(f"PR template not found at {path}, falling back to flat template")
path = templates_dir / REPORT_TEMPLATES["flat"]
if not path.exists():
missing = FileNotFoundError(f"Report template not found: {path}")
missing.filename = str(path)
raise missing
return path.read_text(encoding="utf-8")
def _missing_template_page(path: Any) -> str:
"""The page :func:`generate_html_report` returns when its template is missing."""
return f"""<!DOCTYPE html>
<html>
<head><title>Report Error</title></head>
<body>
<h1>Error: Template Not Found</h1>
<p>Could not find template at: {path}</p>
<p>Please ensure the template file exists.</p>
</body>
</html>"""
def _overlay_guard_skips(report_data: Dict[str, Any], guard: Optional[Dict[str, Any]]) -> int:
"""Badge each group the commit apply guard skipped: ``guardSkip: {reason, files, label}``
on the group, where
the label reads "skipped: file changed since ``<head7>``" or "skipped:
context plan". A replacement, like the decision overlay: a stamp from an
earlier overlay that this guard does not name is dropped. Returns the
number of groups stamped."""
skipped = (guard or {}).get("skipped") or {}
head = str((guard or {}).get("head") or "")
stamped = 0
for group in report_data.get("groups", []):
group.pop("guardSkip", None)
entry = skipped.get(group.get("groupHash") or "")
if not isinstance(entry, dict):
continue
reason = str(entry.get("reason") or "")
label = ("skipped: context plan" if reason == "context_plan"
else f"skipped: file changed since {head[:7]}")
group["guardSkip"] = {
"reason": reason,
"files": [str(f) for f in entry.get("files") or []],
"label": label,
}
stamped += 1
return stamped
def regenerate_report_with_human_decisions(
phase_dir: Path,
human_decisions: Dict[str, Dict[str, Any]],
template_style: Optional[str] = None,
*,
guard: Optional[Dict[str, Any]] = None,
scope_state: Optional[Mapping[str, Any]] = None,
include_consolidated: bool = True,
) -> Tuple[Optional[Path], int]:
"""Re-render ``{phase_dir}/report.html`` with human decisions overlaid.
Loads the ``report_data.json`` sidecar (persisted at review time), overlays
the supplied human decisions (keyed by ``group_hash``), and re-embeds into
the template — no reconstruction of the original runtime inputs
(diff_data, base_ref, models, ...).
Returns ``(report_path, matched)`` on success, or ``(None, 0)`` if the
sidecar is missing (e.g. a report generated before this feature existed)
so callers can warn and continue rather than crash. ``matched`` is
``_overlay_human_decisions``'s own count — the number of decisions that
actually joined a group by ``group_hash`` — so a caller can tell "wrote a
report" from "wrote a report that matched what it was handed": a code-review
report whose groups carry no ``groupHash`` (F2) re-renders byte-identical
with ``matched == 0`` and no error, which only the count exposes.
Scope: each group's scope
eligibility is recomputed for the round's current effective policy and
recorded deferrals (*scope_state*: the ``state.json`` dict; ``None`` reads
the one beside *phase_dir*), keeping the persisted classification intact.
With *include_consolidated* the consolidated page is regenerated from its
own sidecar too (:func:`regenerate_consolidated_with_human_decisions`,
best-effort).
"""
phase_dir = Path(phase_dir)
sidecar = phase_dir / "report_data.json"
if not sidecar.exists():
return None, 0
if scope_state is None:
scope_state = _scope_report.read_state(phase_dir)
report_data = upgrade_legacy(json.loads(sidecar.read_text(encoding="utf-8")))
matched = _overlay_human_decisions(report_data, human_decisions or {})
# The commit guard's skips, read from the saved guard beside the
# decisions (*guard*: the pinned record's ``guard``, None on a plan's run).
_overlay_guard_skips(report_data, guard)
_overlay_scope(report_data, scope_state)
style = template_style or report_data.get("templateStyle", "pr")
html = embed_report_data(report_data, load_report_template(style))
report_path = phase_dir / "report.html"
_write_atomic(report_path, html)
# Keep the sidecar in sync so a subsequent re-run overlays cleanly.
try:
_write_atomic(sidecar, sidecar_json(report_data))
except OSError:
pass
if include_consolidated:
try:
regenerate_consolidated_with_human_decisions(
phase_dir, human_decisions, scope_state=scope_state)
except Exception as exc: # noqa: BLE001 - the main report was written
logger.warning("consolidated report not regenerated: %s", exc)
return report_path, matched
def _overlay_consolidated(report_data: Dict[str, Any],
human_decisions: Mapping[str, Mapping[str, Any]],
scope_state: Optional[Mapping[str, Any]]) -> int:
"""Overlay decisions and scope eligibility onto a consolidated payload (in place).
Decisions act on groups, so they join each umbrella's **underlying**
groups by ``groupHash`` (a replacement, as for the main report). Each
underlying group's scope decision is recomputed for the round's policy
and each umbrella's derived tag rebuilt from its members. Returns the
number of underlying groups a decision joined.
"""
summary = {"approved": 0, "salvaged": 0, "skipped": 0, JUDGE_DECIDED: 0, "total": 0}
matched = 0
info = _persisted_round(report_data, scope_state)
deferrals = _scope_report.deferral_index(info) if info else {}
distinct: List[Tuple[str, Mapping[str, Any]]] = []
for cg in report_data.get("consolidatedGroups") or []:
if not isinstance(cg, dict):
continue
members: List[Tuple[str, Mapping[str, Any]]] = []
for ug in cg.get("underlyingGroups") or []:
if not isinstance(ug, dict):
continue
ug.pop("humanDecision", None)
group_hash = str(ug.get("groupHash") or "")
if group_hash and group_hash in human_decisions:
decision = _normalize_human_decision(dict(human_decisions[group_hash]))
ug["humanDecision"] = decision
matched += 1
summary["total"] += 1
if decision["outcome"] in summary:
summary[decision["outcome"]] += 1
if decision[JUDGE_DECIDED]:
summary[JUDGE_DECIDED] += 1
if info is not None:
_rescope(ug, info, deferrals)
entry = ug.get(_scope_report.ENTRY_KEY) or {}
label = str(ug.get("displayLabel") or f"G{ug.get('groupIndex', '')}")
members.append((label, entry))
distinct.append((group_hash or f"index:{ug.get('groupIndex')}", entry))
if info is not None:
cg[_scope_report.ENTRY_KEY] = _scope_report.umbrella_scope(members)
if info is not None:
report_data[_scope_report.REPORT_KEY] = _scope_report.report_block(
info, _scope_report.count_entries(distinct))
report_data["humanDecisionsSummary"] = summary
return matched
def regenerate_consolidated_with_human_decisions(
phase_dir: Path,
human_decisions: Mapping[str, Mapping[str, Any]],
*,
scope_state: Optional[Mapping[str, Any]] = None,
) -> Tuple[Optional[Path], int, str]:
"""Re-render ``consolidated-report.html`` from ``consolidated_report_data.json``.
The consolidated twin of :func:`regenerate_report_with_human_decisions`:
the persisted payload plus the recorded decisions (overlaid onto the
underlying groups by id) and the round's scope record — never the plan,
``consolidated.json`` or a model. Returns ``(path, matched, status)``:
``regenerated``; ``legacy`` when the page exists but predates the
sidecar (left untouched: it cannot be rebuilt from saved data, and
reconstructing it would be a guess); ``absent`` when there is no
consolidated page at all.
"""
phase_dir = Path(phase_dir)
sidecar = phase_dir / CONSOLIDATED_REPORT_DATA
page = phase_dir / CONSOLIDATED_REPORT_HTML
if not sidecar.exists():
return None, 0, ("legacy" if page.exists() else "absent")
if scope_state is None:
scope_state = _scope_report.read_state(phase_dir)
report_data = upgrade_legacy(json.loads(sidecar.read_text(encoding="utf-8")))
matched = _overlay_consolidated(report_data, human_decisions or {}, scope_state)
_write_atomic(page, embed_report_data(report_data, load_report_template("consolidated")))
try:
_write_atomic(sidecar, sidecar_json(report_data))
except OSError:
pass
return page, matched, "regenerated"
def scope_regeneration_needed(phase_dir: Path, scope_state: Optional[Mapping[str, Any]]) -> bool:
"""Whether the round's scope record changes what a saved report shows.
True when recomputing eligibility for the recorded effective policy and
deferrals (an apply override, a deferral the apply phase recorded) would
change ``report_data.json``'s page — so a phase that decided nothing by
hand still refreshes its report when the policy moved.
"""
sidecar = Path(phase_dir) / "report_data.json"
try:
report_data = json.loads(sidecar.read_text(encoding="utf-8"))
except (OSError, ValueError):
return False
if not isinstance(report_data, dict):
return False
return _overlay_scope(report_data, scope_state)
#: ``apply-code-fixes`` is the one apply phase whose mode word is not its
#: ``phase_name`` (the state.json key and phase-dir word the orchestrator
#: itself reads/writes through, e.g. ``ApplyCodeFixesOrchestrator.phase_name``
#: in ``apply_code_fixes_orchestrator.py``, ``"apply-fixes"``) — mirrors
#: ``full_workflow_orchestrator.WRITE_PHASE_DIRS`` and ``display_decisions
#: .resolve_output_file``'s ``phase_map``. ``apply-suggestions`` and
#: ``apply-task-suggestions`` need no entry: their mode word already equals
#: their phase_name.
_APPLY_PHASE_STATE_KEYS = {
"apply-code-fixes": "apply-fixes",
}
def _read_human_decisions_from_state(
state_file: Path, apply_phase: str
) -> Dict[str, Dict[str, Any]]:
"""Read ``human_decisions_{apply_phase}`` from a state.json file.
``apply_phase`` is normalized through ``_APPLY_PHASE_STATE_KEYS`` first, so
a caller (the instructions, a human at the CLI) may pass either the mode
word (``apply-code-fixes``) or the phase_name it is stored under
(``apply-fixes``) and land on the same decisions.
"""
state = upgrade_legacy(json.loads(Path(state_file).read_text(encoding="utf-8")))
key_phase = _APPLY_PHASE_STATE_KEYS.get(apply_phase, apply_phase)
return state.get(f"human_decisions_{key_phase}", {}) or {}
def _read_guard_from_state(state_file: Path) -> Optional[Dict[str, Any]]:
"""The commit apply guard saved in a state.json file (the pinned record's
``guard``), or None."""
try:
state = json.loads(Path(state_file).read_text(encoding="utf-8"))
except (OSError, ValueError):
return None
if not isinstance(state, dict):
return None
# `commit_range.pinned_record`'s order: keep the two in step.
for key in ("commit_range", "head_ref"):
record = state.get(key)
if isinstance(record, dict):
guard = record.get("guard")
return guard if isinstance(guard, dict) else None
return None
def _read_state_dict(state_file: Path) -> Dict[str, Any]:
"""A state.json file as a dict (``{}`` when unreadable)."""
return _read_state_document(state_file) or {}
def _report_consolidated_regeneration(phase_dir: Path, decisions: Mapping[str, Any],
scope_state: Mapping[str, Any]) -> None:
"""Regenerate the consolidated page beside a report and say what happened."""
try:
path, matched, status = regenerate_consolidated_with_human_decisions(
phase_dir, decisions, scope_state=scope_state)
except Exception as exc: # noqa: BLE001 - best-effort, like the main overlay
print(f"WARNING: consolidated report not regenerated: {exc}", file=sys.stderr)
return
if status == "regenerated":
print(f"Consolidated HTML report regenerated with {matched} of {len(decisions)} "
f"decision(s) matched by underlying group: {path}")
elif status == "legacy":
print(f"{Path(phase_dir) / CONSOLIDATED_REPORT_HTML} predates "
f"{CONSOLIDATED_REPORT_DATA}, so it cannot be regenerated from saved "
"data and is left as it was (run --consolidate again to refresh it).")
def main(argv: Optional[List[str]] = None) -> int:
"""CLI: overlay recorded human decisions onto an existing review report."""
bootstrap_streams()
parser = argparse.ArgumentParser(
description=(
"Regenerate an HTML review report with human/judge-agent decisions overlaid."
)
)
sub = parser.add_subparsers(dest="command", required=True)
rd = sub.add_parser(
"regenerate-decisions",
help="Overlay recorded human decisions onto an existing review report.html",
)
rd.add_argument(
"--phase-dir",
required=True,
help="Review phase dir containing report_data.json / report.html",
)
rd.add_argument(
"--state-file",
required=True,
help="state.json holding human_decisions_{apply-phase}",
)
rd.add_argument(
"--apply-phase",
required=True,
help=(
"Apply phase name, e.g. apply-suggestions / apply-code-fixes / "
"apply-task-suggestions"
),
)
rd.add_argument(
"--template-style",
default=None,
help="Override template style (pr/flat); defaults to the original style",
)
args = parser.parse_args(argv)
if args.command == "regenerate-decisions":
phase_dir = Path(args.phase_dir)
decisions = _read_human_decisions_from_state(
Path(args.state_file), args.apply_phase
)
guard = _read_guard_from_state(Path(args.state_file))
scope_state = _read_state_dict(Path(args.state_file))
if (not decisions and not (guard or {}).get("skipped")
and not scope_regeneration_needed(phase_dir, scope_state)
and (phase_dir / "report_data.json").exists()):
# Live run 8: a phase that decided
# nothing by hand or by judge re-rendered the report anyway and
# printed "0 of 0 human decision(s) matched", which the host
# relayed. The executor leg's twin
# (`ApplyPhaseReport.regenerate_decisions_overlay`) has
# always left the report alone then; this leg now does too.
print(
f"No human or judge decisions are recorded for "
f"{args.apply_phase}, so {phase_dir / 'report.html'} is left "
"as it was."
)
return 0
result, matched = regenerate_report_with_human_decisions(
phase_dir, decisions, args.template_style, guard=guard,
scope_state=scope_state, include_consolidated=False,
)
_report_consolidated_regeneration(phase_dir, decisions, scope_state)
if result is None:
print(
f"No report_data.json in {phase_dir}; cannot overlay decisions "
"(report predates the decision-overlay feature). Skipping HTML "
"update."
)
return 0
if not decisions and not (guard or {}).get("skipped"):
# Only the round's scope record moved (an apply override or its
# deferrals): say that, not "0 of 0 decisions matched".
print(f"HTML report regenerated for this round's recorded scope policy "
f"(no human or judge decision is recorded): {result}")
return 0
print(
f"HTML report regenerated with {matched} of {len(decisions)} human "
f"decision(s) matched: {result}"
)
if matched < len(decisions):
print(
f"WARNING: {len(decisions) - matched} decision(s) did not match "
"any group in this report (no groupHash on the group, or the "
"decision's id is stale). The report was still written.",
file=sys.stderr,
)
return 0
return 1
if __name__ == "__main__":
import sys
sys.exit(main(sys.argv[1:]))
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |