pi-dev-team 0.2.0

package/skills/code-review/scripts/changed_file_list.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""Compute a changed-file list with git change-type (#1734).
+
+`arch-review` (and every other `Context needs: project-structure` lens —
+`doc-review`, `domain-review`) has no Bash grant, yet its dispatch payload
+today is only "full files + directory tree". Nothing stops the agent from
+reasoning that it should "see what changed" and attempting `git diff` itself
+— a call it does not have, denied, and surfaced as a spurious error in its
+report. The fix is not a new tool grant (that would be a first-of-its-kind
+precedent for a review agent); it is completing the payload the orchestrator
+already has the data for: a changed/added/removed file list alongside the
+full files and tree.
+
+This module is that data, computed once from `git diff --name-status` output
+so `/code-review` never invents it twice: `SKILL.md` step 4 feeds it into the
+`project-structure` context payload, and step 3 feeds its `added` list into
+`select_lenses.py`'s `--added-from` flag for `component-architecture-review`'s
+added-only `Scope:` gate (#1733) — one changed-file computation, two
+consumers, not two ways to derive the same fact.
+
+**A skipped line narrows, it does not widen.** A line this module cannot
+parse (wrong field count, empty path) is skipped rather than guessed, never
+fabricated — but for the added-only `Scope:` gate that consumes this
+module's `added` list, dropping a genuinely-added path *removes* it from
+`added` while it still reaches `select_lenses.py` independently via
+`--files`, so the gate's `f in added_files` membership test then excludes
+that lens rather than including it. A parse skip is a missed narrowing
+*result* (the lens is lost, not kept) — do not read it as fail-open the way
+this module's caller (`select_lenses.py`) is fail-open for a missing
+`Scope:` declaration; the two failure directions are opposite.
+
+**Only `status == "A"` counts as added — renames and copies do not.** A
+rename (`R`) or copy (`C`) produces a path that did not previously exist,
+but it carries no new content to assess (a rename) or duplicates content
+already reviewed elsewhere (a copy, and only reachable at all when a caller
+passes `-C`/`--find-copies`, which none of this module's callers do today).
+This is a deliberate, narrow choice, not an oversight — widen it (e.g.
+`status in ("A", "C")`) only with a test pinning the new behavior.
+
+**Known limitation: a path git C-quotes is stored quoted, not unquoted.**
+Git always quotes a control character (including an embedded newline) or a
+literal backslash/double-quote in a path — regardless of `core.quotePath` —
+by wrapping it in `"..."` with C-style escapes (verified empirically: a file
+literally named with an embedded newline round-trips through `git diff
+--name-status` as the single line `"a\nb.txt"`, quotes included). This
+module does not strip that quoting, so such a path reaches `select_lenses.py`
+still wrapped in `"..."`, and its `_matches()` suffix check (`.endswith(...)`)
+then fails against every glob — the file is invisible to every non-`always`
+lens. Narrow in practice (control characters in filenames are rare) and not
+a regression this module introduces (the pre-existing `--name-only` listing
+step 1 uses has the identical exposure); fixing it needs a C-quote-aware
+unquote step here, not attempted in this pass.
+
+Pure policy except for the one I/O boundary in `main()` (reading
+`--name-status-from <file>`, guarded against a missing/unreadable path).
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Iterable
+
+
+def parse_name_status(lines: Iterable[str]) -> list[dict]:
+    """Parse `git diff --name-status` lines into `[{"path", "status"}, ...]`.
+
+    Each line is `<status>\\t<path>`, or for a rename/copy
+    `<status>\\t<old-path>\\t<new-path>` — the last field is always the
+    current path, which is what every consumer here cares about. `status` is
+    normalized to its leading letter (`R100` -> `R`) so callers compare
+    against `A`/`M`/`D`/`R`/`C` without parsing similarity percentages.
+    Unparseable lines are skipped, never raised on and never guessed.
+    """
+    files: list[dict] = []
+    for raw in lines:
+        line = raw.rstrip("\n")
+        if not line.strip():
+            continue
+        parts = line.split("\t")
+        if len(parts) < 2:
+            continue
+        status_field = parts[0].strip()
+        path = parts[-1].strip()
+        if not status_field or not path:
+            continue
+        files.append({"path": path, "status": status_field[0]})
+    return files
+
+
+def evaluate(lines: Iterable[str]) -> dict:
+    """Evaluate `git diff --name-status` lines into the full result dict."""
+    files = parse_name_status(lines)
+    return {
+        "files": files,
+        "added": [f["path"] for f in files if f["status"] == "A"],
+    }
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--name-status", nargs="*", default=[],
+        help="git diff --name-status lines, one per arg (space-separated)",
+    )
+    parser.add_argument(
+        "--name-status-from", default=None,
+        help="read newline-separated name-status lines from this file ('-' for stdin)",
+    )
+    args = parser.parse_args(argv)
+
+    lines = list(args.name_status)
+    if args.name_status_from:
+        try:
+            if args.name_status_from == "-":
+                text = sys.stdin.read()
+            else:
+                with open(args.name_status_from) as handle:
+                    text = handle.read()
+        except (OSError, ValueError):
+            # Missing/unreadable path, closed stdin, or undecodable bytes:
+            # contribute no lines rather than crash the whole invocation —
+            # consistent with every other unparseable-input case in this
+            # module. `ValueError` also covers `UnicodeDecodeError` (a
+            # subclass), reachable here because SKILL.md's caller mandates
+            # `-c core.quotePath=false`, which makes git emit raw path bytes
+            # instead of escaped octal for a non-ASCII path.
+            text = ""
+        lines.extend(line for line in text.splitlines() if line.strip())
+
+    print(json.dumps(evaluate(lines), sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
+
+
+__all__ = ("evaluate", "parse_name_status")

package/skills/code-review/scripts/closing_pass.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""Closing-pass composition for `/code-review`'s fix loop (#1626).
+
+`/code-review` step 6a used to mandate: after ANY fix-loop iteration ran,
+re-dispatch the **full** original agent panel once more against the final
+staged content. The reason was structural, not editorial — the pre-commit
+gate (#1461) needed `>= 2` distinct dispatches whose `subject_hash` equals the
+FINAL staged hash, and the loop's targeted re-dispatches only cover the
+agents that happened to have findings. So a one-line fix re-triggered an
+18-agent panel. That is the single biggest cost multiplier in the loop, and
+#1619 paid it repeatedly.
+
+This module computes the **closing pass** instead: the minimal dispatch set
+that preserves both properties the full re-panel was defending.
+
+## The two properties, and how each is preserved
+
+1. **The gate's corroboration floor, satisfied by construction.**
+   `hooks/pre_pr_review.py`'s `_MIN_DISTINCT_DISPATCHES` is 1 (#2147; lowered
+   from 2 — a single `/code-review` dispatch already runs a full panel
+   internally, so a second top-level dispatch was never additional
+   corroboration). The composition rule below tops up from the resolver's
+   eligible roster until at least that many distinct registered agents
+   dispatch at the final hash. No hook change, no exemption event, no ledger
+   change — the floor is met the same way it is met today, just with 1-2
+   dispatches instead of 18 (previously 2-3, under the old floor of 2).
+
+2. **Not a rubber stamp.** Closing-pass agents keep full review authority:
+   any actionable finding re-enters the fix loop exactly as before (subject
+   to #1625's round cap). What changes is *how many* agents re-read *how
+   much* content — never whether their findings count. A pass whose findings
+   carried no consequence would be exactly the "dispatch trivial calls purely
+   to clear the gate" abuse `pre_commit_review.py`'s own docstring names.
+
+## Scope: the fix delta, not the whole changeset
+
+The round-1 panel already reviewed the full changeset. Only the *fix delta*
+— what changed between what the panel reviewed and the final staged content
+— is unreviewed. The closing pass reviews that delta.
+
+**Escape hatch.** If the fix delta touches files the original panel never
+targeted, scope grew mid-loop and the delta-only argument no longer holds:
+fall back to the full re-dispatch over the whole changeset. That condition is
+a deterministic set-comparison of two file lists, checked here rather than
+judged in prose.
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+#: Mirrors `hooks/pre_pr_review.py`'s `_MIN_DISTINCT_DISPATCHES`. Kept as
+#: a named constant here (rather than imported) because this script must not
+#: depend on the hook package to compute a dispatch plan; the drift test in
+#: `plugins/dev-team/tests/scripts/test_closing_pass.py` asserts the two stay
+#: equal, so a future change to the gate's floor fails a test rather than
+#: silently under-composing the closing pass.
+MIN_DISTINCT_DISPATCHES = 1
+
+
+def _normalize(path) -> str:
+    text = str(path or "").replace("\\", "/")
+    while text.startswith("./"):
+        text = text[2:]
+    return text
+
+
+def scope_grew(panel_files, fix_delta_files) -> bool:
+    """True when the fix delta touches a file the original panel never
+    targeted — the escape-hatch condition. A pure set comparison."""
+    panel = {_normalize(p) for p in panel_files if str(p or "").strip()}
+    delta = {_normalize(p) for p in fix_delta_files if str(p or "").strip()}
+    return not delta.issubset(panel)
+
+
+def compose(
+    fixed_by_agents,
+    eligible_roster,
+    panel_agents,
+    panel_files=(),
+    fix_delta_files=(),
+    minimum: int = MIN_DISTINCT_DISPATCHES,
+) -> dict:
+    """Compute the closing-pass dispatch plan.
+
+    Args:
+        fixed_by_agents: agents whose findings were fixed during the loop.
+            Each verifies its own fixes at the final hash.
+        eligible_roster: the resolver's eligible lenses in `select_lenses.py`
+            order — cheap-first (non-opus before opus). Top-ups are taken
+            from the front, so a top-up never reaches for an opus lens while
+            a cheaper eligible one is available.
+        panel_agents: the full round-1 panel, used only by the escape hatch.
+        panel_files / fix_delta_files: drive `scope_grew`.
+        minimum: the gate's distinct-dispatch floor.
+
+    Returns `{"agents", "scope", "escape_hatch", "reason", "topped_up"}`.
+    `scope` is `fix-delta` normally, `full-changeset` under the escape hatch.
+    """
+    fixed = _dedupe(fixed_by_agents)
+    roster = _dedupe(eligible_roster)
+    panel = _dedupe(panel_agents)
+
+    if scope_grew(panel_files, fix_delta_files):
+        return {
+            "agents": panel or roster,
+            "scope": "full-changeset",
+            "escape_hatch": True,
+            "reason": "fix-delta-touched-files-outside-the-panel-target-set",
+            "topped_up": [],
+        }
+
+    agents = list(fixed)
+    topped_up = []
+    for candidate in roster:
+        if len(agents) >= minimum:
+            break
+        if candidate not in agents:
+            agents.append(candidate)
+            topped_up.append(candidate)
+
+    reason = None
+    if len(agents) < minimum:
+        # The eligible roster itself cannot supply the floor (a tiny or
+        # heavily-filtered roster). Say so explicitly rather than emitting a
+        # plan that will fail the gate for reasons the operator can't see.
+        reason = "eligible-roster-smaller-than-gate-floor"
+
+    return {
+        "agents": agents,
+        "scope": "fix-delta",
+        "escape_hatch": False,
+        "reason": reason,
+        "topped_up": topped_up,
+    }
+
+
+def _dedupe(values) -> list:
+    seen, out = set(), []
+    for value in values or ():
+        name = str(value or "").strip()
+        if name and name not in seen:
+            seen.add(name)
+            out.append(name)
+    return out
+
+
+def _load_list(value: str | None) -> list:
+    """Accept either a comma-separated inline list or `@path` to a JSON file
+    holding a list (or `{"lenses": [...]}`, matching `select_lenses.py`)."""
+    if not value:
+        return []
+    if value.startswith("@"):
+        data = json.loads(Path(value[1:]).read_text(encoding="utf-8"))
+        if isinstance(data, dict):
+            data = data.get("lenses", data.get("agents", []))
+        return list(data) if isinstance(data, list) else []
+    return [v.strip() for v in value.split(",") if v.strip()]
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(description="Compose the /code-review closing pass.")
+    parser.add_argument("--fixed-by", default="", help="Agents whose findings were fixed")
+    parser.add_argument("--roster", default="", help="Eligible roster, cheap-first (or @file.json)")
+    parser.add_argument("--panel", default="", help="The full round-1 panel (or @file.json)")
+    parser.add_argument("--panel-files", default="", help="Files the round-1 panel targeted")
+    parser.add_argument("--fix-delta-files", default="", help="Files the cumulative fix touched")
+    args = parser.parse_args(argv)
+
+    plan = compose(
+        _load_list(args.fixed_by),
+        _load_list(args.roster),
+        _load_list(args.panel),
+        _load_list(args.panel_files),
+        _load_list(args.fix_delta_files),
+    )
+    print(json.dumps(plan, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/skills/code-review/scripts/consolidate.py

@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+"""Consolidate per-slice section artifacts into one deduplicated report.
+
+Split into a **pure** ``consolidate(sections)`` (takes a list of section dicts,
+returns the aggregated object) and a thin ``main()`` that reads
+``.dev-team-reports/code-review/raw/section-*.json`` and calls it — the same
+main-wraps-pure convention as ``check_version_drift.py``/``lesson_validate.py``,
+so the aggregation logic is unit-tested with plain dicts and no filesystem.
+
+Consolidation:
+- Dedupe findings by ``file:line`` — one entry, reporting agents merged into an
+  ``agents[]`` array, severity = the single highest enum (per SKILL.md step 5c).
+- Recurring-theme rollup — a review dimension (agent) whose findings recur across
+  two or more slices, so a systemic pattern surfaces above per-slice noise.
+- Disclose which slices ran the reduced (declarative) panel.
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import sys
+from pathlib import Path
+
+# Reach the sibling ledger.py regardless of cwd or sys.path mode (matches the
+# house pattern in change_shape.py/codebase_recon.py for reaching a sibling
+# module rather than relying on the implicit sys.path[0] a direct script
+# invocation provides).
+_HERE = Path(__file__).resolve().parent
+if str(_HERE) not in sys.path:
+    sys.path.insert(0, str(_HERE))
+
+from ledger import raw_dir
+
+# Single source of truth for the severity vocabulary (step 5c's ranking lived
+# only in prose before): each severity's rank (for highest-wins merge and
+# sorting) and its totals bucket key.
+_SEVERITY = {
+    "suggestion": (1, "suggestions"),
+    "warning": (2, "warnings"),
+    "error": (3, "errors"),
+}
+_DEFAULT_SEVERITY = "suggestion"
+
+# A review dimension recurring across at least this many slices is a theme.
+_THEME_MIN_SLICES = 2
+
+# Real-world review-agent output drifts from the documented schema (#1261): some
+# agents return their findings list under `issues` (the per-agent key in
+# output-format.md) instead of `findings` (the section-artifact key). Accept
+# either so a mis-keyed list is aggregated, never silently counted as zero. The
+# canonical key is tried first; the alias is a fallback.
+_FINDINGS_KEYS = ("findings", "issues")
+
+
+def _rank(severity: str) -> int:
+    return _SEVERITY.get(severity, (0, ""))[0]
+
+
+def _bucket(severity: str) -> str:
+    return _SEVERITY.get(severity, _SEVERITY[_DEFAULT_SEVERITY])[1]
+
+
+def _findings_of(container: dict) -> list:
+    """Return the findings list from ``container`` tolerating key drift (#1261).
+
+    Prefers ``findings`` (section-artifact key), falls back to ``issues``
+    (per-agent key). A value that is present but not a list is treated as no
+    findings rather than crashing the aggregation.
+    """
+    for key in _FINDINGS_KEYS:
+        value = container.get(key)
+        if isinstance(value, list):
+            return value
+    return []
+
+
+def normalize_agent_result(raw: dict, agent_name: str | None = None) -> list:
+    """Coerce one review agent's result into a flat, ``agent``-tagged findings list.
+
+    Absorbs the schema drift observed in real runs (#1261): the native per-agent
+    ``{status, issues, summary}`` shape, findings keyed as ``issues`` **or**
+    ``findings``, and any extra top-level keys (e.g. ``summary``) — all of which
+    are ignored except the findings list. Each returned finding is tagged with
+    its reporting ``agent`` (from ``raw["agentName"]``, else ``agent_name``) so
+    ``consolidate()`` can merge reporters per ``file:line`` and roll up themes.
+
+    Non-dict input, or a findings entry that is not a dict, yields an empty list
+    / is skipped — this never raises, so a malformed agent result degrades to
+    "reported nothing" rather than aborting the whole aggregation.
+    """
+    if not isinstance(raw, dict):
+        return []
+    agent = raw.get("agentName") or agent_name
+    out = []
+    for finding in _findings_of(raw):
+        if not isinstance(finding, dict):
+            continue
+        tagged = dict(finding)
+        tagged.setdefault("agent", agent)
+        out.append(tagged)
+    return out
+
+
+def _dedupe_key(finding: dict):
+    return (finding.get("file"), finding.get("line"))
+
+
+def _sorted_ids(ids) -> list:
+    """Return the non-None ids, sorted — the shared 'sorted, None-filtered' idiom."""
+    return sorted(s for s in ids if s is not None)
+
+
+def _merge_finding(merged: dict, order: list, finding: dict) -> None:
+    """Insert ``finding`` into the ``file:line`` dedup map, or merge it into the
+    existing entry: highest severity wins and keeps its message; reporting agents
+    accumulate into ``agents[]`` without duplicates.
+    """
+    key = _dedupe_key(finding)
+    agent = finding.get("agent")
+    severity = finding.get("severity", _DEFAULT_SEVERITY)
+    entry = merged.get(key)
+    if entry is None:
+        order.append(key)
+        merged[key] = {
+            "severity": severity,
+            "agents": [agent] if agent else [],
+            "file": finding.get("file"),
+            "line": finding.get("line"),
+            "message": finding.get("message"),
+        }
+        return
+    if _rank(severity) > _rank(entry["severity"]):
+        entry["severity"] = severity
+        entry["message"] = finding.get("message")
+    if agent and agent not in entry["agents"]:
+        entry["agents"].append(agent)
+
+
+def _tally_severity(totals: dict, severity: str) -> None:
+    totals[_bucket(severity)] += 1
+
+
+def _tally_theme(theme_slices: dict, theme_counts: dict, agent: str | None, slice_id) -> None:
+    """Record one finding's contribution to the recurring-theme rollup for ``agent``."""
+    if agent is None:
+        return
+    theme_slices.setdefault(agent, set()).add(slice_id)
+    theme_counts[agent] = theme_counts.get(agent, 0) + 1
+
+
+def consolidate(sections: list[dict]) -> dict:
+    """Aggregate ``sections`` into the consolidated report object.
+
+    ``sections`` is a list of per-slice artifacts (``id``/``files``/
+    ``is_declarative``/``panel``/``findings``). Findings carry the usual
+    ``severity``/``file``/``line``/``message`` and an optional ``agent`` naming
+    the reporting review dimension. Returns the aggregated object; an empty input
+    yields an empty (but well-formed) aggregate.
+    """
+    merged: dict = {}          # (file, line) -> consolidated finding
+    order: list = []           # first-seen order of keys, for stable output
+    theme_slices: dict = {}    # agent -> set of slice ids
+    theme_counts: dict = {}    # agent -> total findings
+    reduced_panel_slices: list = []
+    dispatch_failures: list = []
+    totals = {"errors": 0, "warnings": 0, "suggestions": 0}
+
+    for section in sections:
+        slice_id = section.get("id")
+        if section.get("is_declarative"):
+            reduced_panel_slices.append(slice_id)
+        section_dispatch_failures = section.get("dispatchFailures")
+        if isinstance(section_dispatch_failures, list):
+            dispatch_failures.extend(section_dispatch_failures)
+        for finding in _findings_of(section):
+            severity = finding.get("severity", _DEFAULT_SEVERITY)
+            _tally_severity(totals, severity)
+            _tally_theme(theme_slices, theme_counts, finding.get("agent"), slice_id)
+            _merge_finding(merged, order, finding)
+
+    top_findings = [merged[k] for k in order]
+    top_findings.sort(key=lambda f: (-_rank(f["severity"]), str(f["file"]), f["line"] or 0))
+
+    recurring_themes = [
+        {"agent": agent, "slices": _sorted_ids(slices), "occurrences": theme_counts[agent]}
+        for agent, slices in theme_slices.items()
+        if len(slices) >= _THEME_MIN_SLICES
+    ]
+    recurring_themes.sort(key=lambda t: (-t["occurrences"], t["agent"]))
+
+    overall = "fail" if totals["errors"] else "warn" if totals["warnings"] else "pass"
+    # A non-empty dispatchFailures forces overall: fail, unconditionally — applied
+    # after the totals-based computation above so it always wins, mirroring the
+    # legacy (non-sliced) path's own unconditional-override rule.
+    if dispatch_failures:
+        overall = "fail"
+
+    return {
+        "sliced": True,
+        "sliceCount": len(sections),
+        "overall": overall,
+        "totals": totals,
+        "topFindings": top_findings,
+        "recurringThemes": recurring_themes,
+        "reducedPanelSlices": _sorted_ids(reduced_panel_slices),
+        "dispatchFailures": dispatch_failures,
+        "summary": (
+            f"{overall.upper()} across {len(sections)} slices — "
+            f"{totals['errors']} errors, {totals['warnings']} warnings, "
+            f"{totals['suggestions']} suggestions; "
+            f"{len(recurring_themes)} recurring theme(s)."
+        ),
+    }
+
+
+def _read_sections(root: str) -> tuple[list, list]:
+    """Read every ``raw/section-*.json`` under ``root``.
+
+    Returns ``(sections, malformed_paths)``. A malformed artifact is collected
+    into ``malformed_paths`` (reported by the caller), never silently dropped.
+    """
+    sections, malformed = [], []
+    for path in sorted(glob.glob(str(raw_dir(root) / "section-*.json"))):
+        try:
+            obj = json.loads(Path(path).read_text())
+        except (json.JSONDecodeError, OSError):
+            malformed.append(path)
+            continue
+        # Valid JSON of the wrong shape (list, string, ...) is malformed too —
+        # otherwise it would crash consolidate() at section.get(...).
+        if not isinstance(obj, dict):
+            malformed.append(path)
+            continue
+        sections.append(obj)
+    return sections, malformed
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", default=".")
+    args = parser.parse_args(argv)
+
+    sections, malformed = _read_sections(args.root)
+    for path in malformed:
+        print(f"WARNING: malformed section artifact skipped: {path}", file=sys.stderr)
+
+    result = consolidate(sections)
+    if malformed:
+        result["malformedArtifacts"] = malformed
+        # A malformed artifact means that slice's findings were never read —
+        # the identical coverage gap `dispatchFailures` forces `overall`
+        # to "fail" for a few lines up in consolidate(), and for the same
+        # reason: an unexamined slice must never ride out as "pass" just
+        # because the READABLE sections happened to look clean (#1763
+        # security review — /pr --json checks only overall/status). The
+        # `summary` string is rebuilt too (#1865) — it must not interpolate
+        # the PRE-override `result['summary']` (built from `overall` INSIDE
+        # consolidate(), before this override runs): doing so would print a
+        # "FAIL ... ; WARN ..." self-contradicting summary. Rebuild it
+        # entirely from the already-available totals/recurringThemes instead.
+        result["overall"] = "fail"
+        totals = result["totals"]
+        result["summary"] = (
+            f"FAIL across {len(sections)} slices — {len(malformed)} malformed "
+            f"artifact(s) unreadable; {totals['errors']} errors, {totals['warnings']} warnings, "
+            f"{totals['suggestions']} suggestions from readable slices; "
+            f"{len(result['recurringThemes'])} recurring theme(s)."
+        )
+    print(json.dumps(result, indent=2, sort_keys=True))
+    # Non-zero exit if any artifact was unreadable, so a caller notices.
+    return 2 if malformed else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))