dsh-compound-engineering 0.0.0-stage → 0.1.0

package/skills/ce-code-review/scripts/review-scope.py

@@ -0,0 +1,419 @@
+#!/usr/bin/env python3
+"""Compute fail-closed, deterministic scope facts for ce-code-review.
+
+The helper never awards lite. It reports counts, path classes, and floors
+the skill's Review depth gate reads. `hard_block_full` forces the full
+spine: a path class the script can name, a file it could not count, or a
+change whose executable non-test lines reach the full floor. Below that
+floor, size is a fact the gate reads, never a decision; the agent judges
+consequence.
+"""
+
+from __future__ import annotations
+
+import argparse
+import functools
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+CODE_EXTENSIONS = {
+    ".rb", ".py", ".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx", ".go", ".rs",
+    ".java", ".swift", ".kt", ".c", ".cc", ".cpp", ".cs", ".php",
+    ".ex", ".exs", ".scala",
+    ".sh", ".bash", ".zsh", ".fish", ".ps1", ".pl", ".pm", ".lua", ".dart",
+    ".vue", ".svelte",
+}
+
+SIGNAL_PATTERNS = {
+    "migrations": re.compile(
+        r"db/migrate/|schema\.(rb|sql)|/migrations?/|alembic|flyway|liquibase",
+        re.I,
+    ),
+    "frontend": re.compile(
+        r"\.(tsx|jsx|vue|svelte|css|scss|html|erb|haml)$|/components?/|stimulus|turbo",
+        re.I,
+    ),
+    "api": re.compile(
+        r"/(routes?|controllers?|api|serializers?|graphql)/|\.proto$|openapi|swagger",
+        re.I,
+    ),
+    "swift-ios": re.compile(r"\.(swift|kt|pbxproj|xcconfig|entitlements)$", re.I),
+}
+
+# Classes the script can name from paths alone. These force full; they do not
+# award lite.
+HARD_BLOCK_PATTERNS = {
+    "migrations": SIGNAL_PATTERNS["migrations"],
+}
+
+# Silent-pass guards the script can name from paths alone. These forbid lite
+# (the change needs the adversarial read the focused path carries) but do not
+# force full; consequence still decides focused versus full. Silent-pass guards
+# outside these paths are the agent's question.
+SILENT_PASS_PATTERNS = {
+    "ci": re.compile(
+        r"(^|/)\.github/workflows/|(^|/)\.gitlab-ci\.yml$|(^|/)\.gitlab-ci/"
+        r"|(^|/)Jenkinsfile$|(^|/)\.circleci/|(^|/)\.buildkite/",
+        re.I,
+    ),
+}
+
+# Executable non-test changed lines at or above this run the full spine; it
+# matches the maintainability reviewer's trigger. Below it, consequence decides.
+# Whole-file deletions never count toward it: they band separately, and that
+# band can forbid lite but never forces full.
+FULL_EXEC_LINE_MIN = 200
+
+# Conventions recognized: tests?/spec/__tests__ directories; a .test./.spec.
+# suffix; a test_*.py / conftest.py Python prefix; and a case-sensitive
+# Test/Tests/Spec class-file suffix (Java/C#/Scala/Swift/Kotlin), so that
+# Contest.java or Manifest.cs stays production code.
+TEST_PATTERN = re.compile(
+    r"(^|/)(tests?|spec|__tests__)/"
+    r"|(^|/)[^/]+[._-](test|spec)\.[^/]+$"
+    r"|(^|/)(test_[^/]+|conftest)\.[^/]+$"
+    r"|(?-i:(^|/)[^/]+(Test|Tests|Spec)\.(java|kt|scala|swift|cs)$)",
+    re.I,
+)
+AGENT_SURFACE_PATTERN = re.compile(
+    r"(^|/)(skills?|agents?|prompts?|tools?|mcp|commands?)(/|$)|SKILL\.md$|"
+    r"(^|/)(AGENTS|CLAUDE|GEMINI)\.md$|\.cursor/|\.codex-plugin/|\.claude-plugin/",
+    re.I,
+)
+
+
+def git(*args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", *args], capture_output=True, text=True, check=False
+    )
+
+
+def valid_commit(ref: str | None) -> bool:
+    if not ref:
+        return False
+    return git("rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}").returncode == 0
+
+
+def unique_merge_base(base: str, head: str) -> str | None:
+    result = git("merge-base", "--all", base, head)
+    candidates = [line for line in result.stdout.splitlines() if line]
+    if result.returncode != 0 or len(candidates) != 1:
+        return None
+    return candidates[0]
+
+
+DEFAULT_DOCS_ROOT = "docs"
+
+
+def normalize_docs_root(docs_root: str | None) -> str:
+    """Fall back to the default root for an unset, empty, or unsubstituted value.
+
+    The calling skill substitutes a resolved path for the ``<root>`` placeholder
+    before invoking this script. If that substitution is missing — the value is
+    empty, or still contains angle brackets (a literal ``<root>``) — treat it as
+    unset and use the default ``docs``, which is exactly the block's unset
+    behavior. This keeps the common default-config case correct even when the
+    caller forgets to substitute.
+    """
+    if not docs_root or "<" in docs_root or ">" in docs_root:
+        return DEFAULT_DOCS_ROOT
+    return docs_root
+
+
+@functools.lru_cache(maxsize=None)
+def repo_root() -> Path:
+    """The repository root, matching how docs_root is resolved everywhere else.
+
+    docs_root is repo-relative (``<repo-root>/<docs_root>``), so the corpus
+    check must resolve against the git toplevel, not the current working
+    directory. ce-code-review can run from a subdirectory (``git diff`` still
+    works there), where ``Path.cwd()`` would join docs_root under the subdir and
+    wrongly report the corpus absent. Fall back to cwd when git can't answer.
+    """
+    result = git("rev-parse", "--show-toplevel")
+    if result.returncode == 0 and result.stdout.strip():
+        return Path(result.stdout.strip()).resolve()
+    return Path.cwd().resolve()
+
+
+def has_learnings_corpus(docs_root: str | None) -> bool:
+    """Whether a `<docs_root>/solutions` learnings corpus exists.
+
+    docs_root is the artifact root resolved by the calling skill (default
+    ``docs``). Guard it the way the skill-prose rule does: normalize an
+    unset/placeholder value to the default, and treat a value that is absolute
+    or escapes the repository as absent rather than probing an out-of-repo path.
+    """
+    docs_root = normalize_docs_root(docs_root)
+    if os.path.isabs(docs_root):
+        return False
+    repo = repo_root()
+    candidate = (repo / docs_root / "solutions").resolve()
+    if repo not in candidate.parents and candidate != repo:
+        return False
+    return candidate.is_dir()
+
+
+PACKS_RESOLVER = Path(__file__).resolve().parent / "packs-resolve.py"
+# Parse-only mode does no git or cache work, so this bound only guards against a
+# wedged interpreter; the helper is meant to be cheap and must never hang scope.
+PACKS_RESOLVER_TIMEOUT = 30.0
+
+
+def declared_packs() -> tuple[bool | None, int]:
+    """Whether the local CE config declares Compound Packs, from the config alone.
+
+    Runs the sibling resolver in `--declared-only` mode, which parses the
+    `packs:` list from both CE config layers and shape-checks each entry with no
+    git or cache work. Its `declared` is true when any entry parsed or the block
+    is malformed -- a broken declaration is still one the learnings pass must
+    surface in Coverage. ``None`` means the helper could not tell (resolver
+    missing, crashed, timed out, or answered without `declared`); the caller
+    then falls closed to reading the config's `packs:` key itself. The second
+    value keeps the `pack_roots` output slot and is always 0: nothing resolves
+    here.
+    """
+    if not PACKS_RESOLVER.is_file():
+        return None, 0
+    try:
+        proc = subprocess.run(
+            [sys.executable, str(PACKS_RESOLVER), "--declared-only"],
+            capture_output=True,
+            text=True,
+            check=False,
+            cwd=repo_root(),
+            timeout=PACKS_RESOLVER_TIMEOUT,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None, 0
+    if proc.returncode != 0:
+        return None, 0
+    try:
+        data = json.loads(proc.stdout)
+    except ValueError:
+        return None, 0
+    declared = data.get("declared") if isinstance(data, dict) else None
+    if not isinstance(declared, bool):
+        return None, 0
+    return declared, 0
+
+
+def repo_signals(docs_root: str | None, local_scope: bool) -> dict[str, object]:
+    """Facts about the repo, not the diff: present in every result shape.
+
+    `declared_packs` describes the local checkout's config, which is not the
+    reviewed tree's config in remote scope, so it is evaluated only when
+    `local_scope` is true and reported as ``None`` otherwise.
+    """
+    learnings_corpus = has_learnings_corpus(docs_root)
+    declared, pack_roots = declared_packs() if local_scope else (None, 0)
+    return {
+        "has_learnings_corpus": learnings_corpus,
+        "declared_packs": declared,
+        "pack_roots": pack_roots,
+    }
+
+
+def fail_closed(reason: str, signals: dict[str, object]) -> dict[str, object]:
+    return {
+        "status": "unknown",
+        "reason": reason,
+        "exec_lines": None,
+        "exec_nontest_lines": None,
+        "unclassified_lines": {},
+        "changed_lines": None,
+        "uncounted_files": 1,
+        "changed_files": [],
+        "signals": [],
+        "hard_block_classes": ["unknown-scope"],
+        "hard_block_full": True,
+        "silent_pass_classes": [],
+        "size_band": "unknown",
+        "deleted_files": [],
+        "deleted_exec_nontest_lines": None,
+        "deleted_band": "unknown",
+        "test_files_changed": False,
+        "agent_surface": False,
+        **signals,
+    }
+
+
+def size_band_for(exec_nontest_lines: int | None) -> str:
+    """Band the executable non-test lines: `large` is a full-spine floor.
+
+    Sources the extension list cannot name are not banded; they are reported
+    in `unclassified_lines` for the gate's consequence judgment.
+    """
+    if exec_nontest_lines is None:
+        return "unknown"
+    if exec_nontest_lines >= FULL_EXEC_LINE_MIN:
+        return "large"
+    return "small"
+
+
+def deleted_band_for(deleted_files: list[str], deleted_exec_nontest_lines: int) -> str:
+    if not deleted_files:
+        return "none"
+    if deleted_exec_nontest_lines >= FULL_EXEC_LINE_MIN:
+        return "large"
+    return "small"
+
+
+def matching_classes(
+    files: list[str], patterns: dict[str, re.Pattern[str]]
+) -> list[str]:
+    return [
+        name
+        for name, pattern in patterns.items()
+        if any(pattern.search(file) for file in files)
+    ]
+
+
+def numstat_path(name: str) -> str:
+    """Return the destination path from a `git diff --numstat` rename display name."""
+    if " => " not in name:
+        return name
+    if "{" in name and "}" in name:
+        prefix, rest = name.split("{", 1)
+        old_new, suffix = rest.split("}", 1)
+        _, new = old_new.split(" => ", 1)
+        # A collapsed segment (`a/{b => }/c`) leaves an empty side, so the
+        # rebuilt path would carry `//` and miss every path-class pattern.
+        return re.sub(r"/{2,}", "/", f"{prefix}{new}{suffix}")
+    _, new = name.split(" => ", 1)
+    return new
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--base", required=True)
+    parser.add_argument("--head")
+    parser.add_argument("--docs-root", default="docs")
+    args = parser.parse_args()
+
+    # Remote scope (pr-remote / branch-remote) always passes --head, even when a
+    # best-effort fetch left it empty; the local config is not that tree's config.
+    repo = repo_signals(args.docs_root, local_scope=args.head is None)
+
+    if not valid_commit(args.base):
+        print(json.dumps(fail_closed("invalid base endpoint", repo), sort_keys=True))
+        return 0
+    if args.head is not None and not valid_commit(args.head):
+        print(json.dumps(fail_closed("invalid head endpoint", repo), sort_keys=True))
+        return 0
+
+    diff_args = [args.base]
+    if args.head:
+        merge_base = unique_merge_base(args.base, args.head)
+        if merge_base is None:
+            print(json.dumps(fail_closed("merge base unavailable or ambiguous", repo), sort_keys=True))
+            return 0
+        diff_args = [merge_base, args.head]
+
+    # Unquoted non-ASCII paths keep extension checks and manifest paths usable.
+    numstat = git("-c", "core.quotePath=false", "diff", "--numstat", *diff_args)
+    raw = git("-c", "core.quotePath=false", "diff", "--raw", *diff_args)
+    if numstat.returncode != 0 or raw.returncode != 0:
+        print(json.dumps(fail_closed("git diff failed", repo), sort_keys=True))
+        return 0
+
+    executable_mode_paths: set[str] = set()
+    deleted_paths: set[str] = set()
+    for line in raw.stdout.splitlines():
+        if "\t" not in line:
+            continue
+        meta, path_field = line.split("\t", 1)
+        fields = meta.lstrip(":").split(" ")
+        if len(fields) < 2:
+            continue
+        if fields[-1] == "D":
+            deleted_paths.add(path_field)
+        old_mode, new_mode = fields[0], fields[1]
+        mode = old_mode if new_mode == "000000" else new_mode
+        if not mode.endswith("755"):
+            continue
+        for path in path_field.split("\t"):
+            executable_mode_paths.add(path)
+
+    files: list[str] = []
+    executable_lines = 0
+    executable_nontest_lines = 0
+    unclassified_lines: dict[str, int] = {}
+    changed_lines = 0
+    uncounted = 0
+    deleted_files: list[str] = []
+    deleted_exec_nontest_lines = 0
+    for line in numstat.stdout.splitlines():
+        parts = line.split("\t")
+        if len(parts) < 3:
+            continue
+        added, deleted, name = parts[0], parts[1], parts[2]
+        resolved_name = numstat_path(name)
+        files.append(resolved_name)
+        ext = Path(resolved_name).suffix.lower()
+        is_exec = ext in CODE_EXTENSIONS or resolved_name in executable_mode_paths
+        is_test = bool(TEST_PATTERN.search(resolved_name))
+        if resolved_name in deleted_paths:
+            deleted_files.append(resolved_name)
+            if deleted.isdigit():
+                changed_lines += int(deleted)
+                if is_exec and not is_test:
+                    deleted_exec_nontest_lines += int(deleted)
+            continue
+        if added == "-" or deleted == "-":
+            uncounted += 1
+            continue
+        try:
+            total = int(added) + int(deleted)
+        except ValueError:
+            uncounted += 1
+            continue
+        changed_lines += total
+        if is_exec:
+            executable_lines += total
+            if not is_test:
+                executable_nontest_lines += total
+        elif not is_test:
+            unclassified_lines[ext] = unclassified_lines.get(ext, 0) + total
+
+    files.sort()
+    deleted_files.sort()
+    signals = matching_classes(files, SIGNAL_PATTERNS)
+    hard_block_classes = matching_classes(files, HARD_BLOCK_PATTERNS)
+    silent_pass_classes = matching_classes(files, SILENT_PASS_PATTERNS)
+    if uncounted:
+        hard_block_classes.append("uncounted")
+    band = size_band_for(executable_nontest_lines)
+
+    result = {
+        "status": "complete",
+        "reason": None,
+        "exec_lines": executable_lines,
+        "exec_nontest_lines": executable_nontest_lines,
+        "unclassified_lines": unclassified_lines,
+        "changed_lines": changed_lines,
+        "uncounted_files": uncounted,
+        "changed_files": files,
+        "signals": signals,
+        "hard_block_classes": hard_block_classes,
+        "hard_block_full": bool(hard_block_classes) or band != "small",
+        "silent_pass_classes": silent_pass_classes,
+        "size_band": band,
+        "deleted_files": deleted_files,
+        "deleted_exec_nontest_lines": deleted_exec_nontest_lines,
+        "deleted_band": deleted_band_for(deleted_files, deleted_exec_nontest_lines),
+        "test_files_changed": any(TEST_PATTERN.search(file) for file in files),
+        "agent_surface": any(AGENT_SURFACE_PATTERN.search(file) for file in files),
+        **repo,
+    }
+    print(json.dumps(result, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/ce-code-review/scripts/run-log.py

@@ -0,0 +1,280 @@
+#!/usr/bin/env python3
+"""Record what a ce-code-review run cost, stage by stage.
+
+`event` appends one JSON line per stage boundary to `<run-dir>/stages.jsonl`
+as the run progresses, so a killed run still leaves parseable partial data.
+`summarize` folds those lines, the run directory's artifact bytes, and any
+peer usage file into a `cost` object merged into `<run-dir>/metadata.json`
+without touching the fields already there. Neither subcommand ever fails
+the run: an error leaves `cost.status` as `unavailable` with the reason.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+STAGES_FILE = "stages.jsonl"
+METADATA_FILE = "metadata.json"
+# Stages whose end marks the receipt being written; a run with one of these
+# ended and no dangling start is complete.
+RECEIPT_STAGES = {"report", "receipt"}
+# The job directory holds detached-runner state, not review output.
+EXCLUDED_DIRS = {"jobs"}
+# Stages that produce candidates; merge and validate only filter them, so
+# their counts stay per stage and never enter the total.
+PRODUCING_STAGES = {"review", "peer", "dispatch"}
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def parse_iso(value: str) -> datetime | None:
+    try:
+        return datetime.fromisoformat(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def host_from_env() -> str:
+    """The same attestation the cross-model reference uses, host only."""
+    env = os.environ
+    seen = [
+        host
+        for host, present in (
+            ("claude", env.get("CLAUDECODE") == "1"),
+            ("codex", any(env.get(k) for k in ("CODEX_SANDBOX", "CODEX_SANDBOX_NETWORK_DISABLED", "CODEX_SESSION_ID", "CODEX_THREAD_ID", "CODEX_CI"))),
+            ("grok", env.get("GROK_AGENT") == "1" or bool(env.get("GROK_SESSION_ID"))),
+        )
+        if present
+    ]
+    if env.get("OMPCODE"):
+        return "omp"
+    if len(seen) == 1:
+        return seen[0]
+    if seen:
+        return "unknown"
+    if env.get("CURSOR_AGENT") or env.get("CURSOR_CONVERSATION_ID"):
+        return "cursor"
+    if env.get("OPENCODE_TERMINAL"):
+        return "opencode"
+    return "unknown"
+
+
+def parse_facts(items: list[str] | None) -> dict[str, object]:
+    facts: dict[str, object] = {}
+    for item in items or []:
+        key, sep, raw = item.partition("=")
+        if not sep or not key:
+            continue
+        try:
+            facts[key] = json.loads(raw)
+        except ValueError:
+            facts[key] = raw
+    return facts
+
+
+def append_line(run_dir: Path, record: dict[str, object]) -> None:
+    run_dir.mkdir(parents=True, exist_ok=True)
+    line = json.dumps(record, sort_keys=True) + "\n"
+    with (run_dir / STAGES_FILE).open("a", encoding="utf-8") as handle:
+        handle.write(line)
+        handle.flush()
+
+
+def cmd_event(args: argparse.Namespace) -> int:
+    run_dir = Path(args.run_dir)
+    if not args.end and not args.start:
+        print("run-log event: nothing to record; pass --end and/or --start", file=sys.stderr)
+        return 0
+    ts = now_iso()
+    extras: dict[str, object] = {}
+    if args.reviewers is not None:
+        extras["reviewers"] = args.reviewers
+    if args.candidates is not None:
+        extras["candidates"] = args.candidates
+    if args.tokens is not None:
+        extras["tokens"] = args.tokens
+    if args.note:
+        extras["note"] = args.note
+    facts = parse_facts(args.fact)
+    if facts:
+        extras["facts"] = facts
+    written = []
+    if args.end:
+        record = {"ts": ts, "stage": args.end, "phase": "end", **extras}
+        append_line(run_dir, record)
+        written.append(record)
+    if args.start:
+        record = {"ts": ts, "stage": args.start, "phase": "start"}
+        # Facts and counts describe the stage that just ended; a lone --start
+        # carries them so the scope stage can record its helper facts.
+        if not args.end:
+            record.update(extras)
+        append_line(run_dir, record)
+        written.append(record)
+    print(json.dumps({"written": written}, sort_keys=True))
+    return 0
+
+
+def read_events(run_dir: Path) -> tuple[list[dict[str, object]], int]:
+    path = run_dir / STAGES_FILE
+    if not path.is_file():
+        raise FileNotFoundError(str(path))
+    events: list[dict[str, object]] = []
+    truncated = 0
+    with path.open("r", encoding="utf-8") as handle:
+        for raw in handle:
+            line = raw.strip()
+            if not line:
+                continue
+            try:
+                parsed = json.loads(line)
+            except ValueError:
+                truncated += 1
+                continue
+            if isinstance(parsed, dict) and "stage" in parsed and "phase" in parsed:
+                events.append(parsed)
+            else:
+                truncated += 1
+    return events, truncated
+
+
+def artifact_bytes(run_dir: Path) -> int:
+    total = 0
+    for root, dirs, files in os.walk(run_dir):
+        dirs[:] = [d for d in dirs if d not in EXCLUDED_DIRS]
+        for name in files:
+            try:
+                total += (Path(root) / name).stat().st_size
+            except OSError:
+                continue
+    return total
+
+
+def peer_usage(run_dir: Path) -> dict[str, object] | None:
+    for path in sorted(run_dir.glob("adversarial-*-usage.json")):
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue
+        if isinstance(data, dict):
+            provider = path.name[len("adversarial-"):-len("-usage.json")]
+            return {"provider": provider, **data}
+    return None
+
+
+def build_cost(run_dir: Path) -> dict[str, object]:
+    events, truncated = read_events(run_dir)
+    stages: list[dict[str, object]] = []
+    order: list[str] = []
+    open_starts: dict[str, dict[str, object]] = {}
+    by_name: dict[str, dict[str, object]] = {}
+    scope_facts: dict[str, object] = {}
+    for event in events:
+        name = str(event["stage"])
+        if name not in by_name:
+            by_name[name] = {"stage": name}
+            order.append(name)
+        entry = by_name[name]
+        if event["phase"] == "start":
+            open_starts[name] = event
+            entry["started_at"] = event.get("ts")
+        elif event["phase"] == "end":
+            entry["ended_at"] = event.get("ts")
+            start = open_starts.pop(name, None)
+            if start is not None:
+                t0, t1 = parse_iso(str(start.get("ts"))), parse_iso(str(event.get("ts")))
+                if t0 and t1:
+                    entry["elapsed_seconds"] = round((t1 - t0).total_seconds(), 3)
+        for key in ("reviewers", "candidates", "tokens", "note"):
+            if key in event:
+                entry[key] = event[key]
+        facts = event.get("facts")
+        if isinstance(facts, dict):
+            entry.setdefault("facts", {}).update(facts)
+            if name == "scope":
+                scope_facts.update(facts)
+    stages = [by_name[name] for name in order]
+    dangling = sorted(open_starts)
+    receipt_done = any(s.get("ended_at") for s in stages if s["stage"] in RECEIPT_STAGES)
+    status = "complete" if receipt_done and not dangling else "partial"
+    totals = {
+        "elapsed_seconds": round(sum(float(s.get("elapsed_seconds", 0) or 0) for s in stages), 3),
+        "reviewers": sum(int(s.get("reviewers", 0) or 0) for s in stages),
+        "candidates": sum(int(s.get("candidates", 0) or 0) for s in stages if s["stage"] in PRODUCING_STAGES),
+        "tokens": sum(int(s.get("tokens", 0) or 0) for s in stages if "tokens" in s),
+        "artifact_bytes": artifact_bytes(run_dir),
+    }
+    if not any("tokens" in s for s in stages):
+        del totals["tokens"]
+    cost: dict[str, object] = {
+        "status": status,
+        "host": host_from_env(),
+        "stages": stages,
+        "totals": totals,
+        "truncated_events": truncated,
+    }
+    if dangling:
+        cost["dangling_stages"] = dangling
+    if scope_facts:
+        cost["scope"] = scope_facts
+    peer = peer_usage(run_dir)
+    if peer is not None:
+        cost["peer"] = peer
+    return cost
+
+
+def cmd_summarize(args: argparse.Namespace) -> int:
+    run_dir = Path(args.run_dir)
+    try:
+        cost = build_cost(run_dir)
+    except FileNotFoundError as exc:
+        cost = {"status": "unavailable", "reason": f"no stage log: {exc}"}
+    except OSError as exc:
+        cost = {"status": "unavailable", "reason": str(exc)}
+    metadata_path = run_dir / METADATA_FILE
+    metadata: dict[str, object] = {}
+    if metadata_path.is_file():
+        try:
+            loaded = json.loads(metadata_path.read_text(encoding="utf-8"))
+            if isinstance(loaded, dict):
+                metadata = loaded
+        except (OSError, ValueError):
+            cost.setdefault("notes", []).append("metadata.json was unreadable and was rewritten")
+    metadata["cost"] = cost
+    run_dir.mkdir(parents=True, exist_ok=True)
+    tmp = metadata_path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(metadata, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    os.replace(tmp, metadata_path)
+    print(json.dumps({"status": cost.get("status"), "metadata": str(metadata_path)}, sort_keys=True))
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    sub = parser.add_subparsers(dest="command", required=True)
+    ev = sub.add_parser("event", help="record a stage boundary")
+    ev.add_argument("--run-dir", required=True)
+    ev.add_argument("--end", help="stage that just ended")
+    ev.add_argument("--start", help="stage that starts now")
+    ev.add_argument("--reviewers", type=int)
+    ev.add_argument("--candidates", type=int)
+    ev.add_argument("--tokens", type=int)
+    ev.add_argument("--note")
+    ev.add_argument("--fact", action="append", help="key=value (value parsed as JSON when possible)")
+    ev.set_defaults(func=cmd_event)
+    sm = sub.add_parser("summarize", help="fold the stage log into metadata.json")
+    sm.add_argument("--run-dir", required=True)
+    sm.set_defaults(func=cmd_summarize)
+    args = parser.parse_args()
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())