@event4u/agent-config 2.12.0 → 2.14.0

package/scripts/audit_cloud_compatibility.py

@@ -207,6 +207,70 @@ def scan() -> list[dict]:
     return rows
 
 
+# step-9 P11 · U3 — Iron-Law bypass scan. Any Python module that loads
+# `agents/.ai-council.yml` directly (yaml.safe_load / open + parse) instead
+# of going through `scripts.ai_council.config.load_council_config` skips the
+# `_reject_top_level_locked_dispatch` gate and is a potential Iron-Law
+# bypass. The scan is intentionally over-broad — false positives are
+# annotated with `# iron-law-ok: …` on the offending line.
+_IRON_LAW_YAML_LOAD_RE = re.compile(
+    r"yaml\.(?:safe_load|load|full_load|unsafe_load)\s*\(",
+)
+_IRON_LAW_AI_COUNCIL_REF_RE = re.compile(
+    r"['\"]\.ai-council\.yml['\"]|ai-council\.yml",
+)
+_IRON_LAW_ALLOWLIST = (
+    # the canonical loader itself
+    "scripts/ai_council/config.py",
+    # tests are allowed to construct synthetic configs directly
+    "tests/",
+    # this audit script's own pattern definitions
+    "scripts/audit_cloud_compatibility.py",
+)
+
+
+def _iron_law_bypass_scan() -> list[dict]:
+    """Scan ``scripts/`` for code that bypasses the Iron-Law validator.
+
+    A bypass is any module that calls a raw YAML loader on a value
+    associated with ``.ai-council.yml`` outside the canonical loader
+    in ``scripts/ai_council/config.py``. Proximity heuristic: the YAML
+    load line, or the 3 lines preceding it, must reference
+    ``ai-council.yml``. Annotate intentional cases with
+    ``# iron-law-ok: <reason>`` on the load line to suppress.
+    """
+    findings: list[dict] = []
+    scripts_dir = ROOT / "scripts"
+    if not scripts_dir.is_dir():
+        return findings
+    for py in sorted(scripts_dir.rglob("*.py")):
+        rel = py.relative_to(ROOT).as_posix()
+        if any(rel.startswith(p) for p in _IRON_LAW_ALLOWLIST):
+            continue
+        try:
+            text = py.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        lines = text.splitlines()
+        offending: list[int] = []
+        for i, line in enumerate(lines, start=1):
+            if not _IRON_LAW_YAML_LOAD_RE.search(line):
+                continue
+            if "iron-law-ok" in line:
+                continue
+            window = "\n".join(lines[max(0, i - 4):i])
+            if _IRON_LAW_AI_COUNCIL_REF_RE.search(window):
+                offending.append(i)
+        if offending:
+            findings.append({
+                "path": rel,
+                "lines": offending,
+                "reason": "raw YAML load on ai-council.yml — bypasses "
+                          "_reject_top_level_locked_dispatch",
+            })
+    return findings
+
+
 def summarize(rows: list[dict]) -> dict:
     by_tier = Counter(r["tier"] for r in rows)
     by_kind_tier: dict[str, Counter] = {}
@@ -251,8 +315,18 @@ def main(argv: list[str] | None = None) -> int:
         help="filter --details to one cloud-action category",
     )
     p.add_argument("--format", choices=["json", "md"], default="json")
+    p.add_argument(
+        "--iron-law",
+        action="store_true",
+        help="scan scripts/ for Iron-Law validator bypasses (step-9 P11 · U3)",
+    )
     args = p.parse_args(argv)
 
+    if args.iron_law:
+        findings = _iron_law_bypass_scan()
+        print(json.dumps({"iron_law_bypass_findings": findings}, indent=2))
+        return 1 if findings else 0
+
     rows = scan()
     summary = summarize(rows)
 

package/scripts/audit_command_surface.py

@@ -0,0 +1,363 @@
+#!/usr/bin/env python3
+"""Command-surface inventory + overlap detection + usage signal.
+
+Walks ``.agent-src.uncompressed/commands/**/*.md``, collects metadata for
+each command (path, description, aliases, line count, last-modified),
+flags overlap pairs by keyword-cosine similarity, and adds a usage
+signal from git history (commands not touched in 90+ days are
+candidates for retirement).
+
+Output:
+  - ``agents/reports/command-surface.json`` (machine-readable)
+  - ``agents/reports/command-surface.md`` (human-readable)
+
+Context: ``agents/roadmaps/step-2-feedback-followup.md`` Phase 1 —
+GPT's PR-#148 "108 commands" cognitive-load warning needs empirical
+verification before any retirement decisions are made.
+
+Usage:
+  python3 scripts/audit_command_surface.py
+  python3 scripts/audit_command_surface.py --root DIR
+  python3 scripts/audit_command_surface.py --quiet
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import re
+import subprocess
+import sys
+from collections import Counter
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from itertools import combinations
+from pathlib import Path
+from typing import List
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_ROOT = REPO_ROOT / ".agent-src.uncompressed" / "commands"
+REPORT_DIR = REPO_ROOT / "agents" / "reports"
+OUT_JSON = REPORT_DIR / "command-surface.json"
+OUT_MD = REPORT_DIR / "command-surface.md"
+
+FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---", re.DOTALL)
+DESCRIPTION_RE = re.compile(r'^description:\s*"?(.*?)"?\s*$', re.MULTILINE)
+ALIASES_RE = re.compile(r"^aliases:\s*(.*)$", re.MULTILINE)
+NAME_RE = re.compile(r"^name:\s*(.*)$", re.MULTILINE)
+CLUSTER_RE = re.compile(r"^cluster:\s*(.*)$", re.MULTILINE)
+TIER_RE = re.compile(r"^tier:\s*(\d+)", re.MULTILINE)
+
+STOPWORDS = {
+    "the", "and", "for", "with", "when", "use", "or", "of", "to", "a", "an",
+    "is", "in", "on", "by", "be", "at", "as", "it", "if", "are", "this",
+    "that", "from", "but", "not", "can", "any", "all", "no", "after",
+    "before", "during", "user", "agent", "code", "project", "via", "into",
+    "onto", "even", "without", "naming", "run", "runs", "running", "each",
+    "every", "one", "two", "now", "then", "also", "based", "default",
+}
+
+OVERLAP_COSINE_THRESHOLD = 0.6
+# Commands with few commits AND younger than this many days since first
+# commit are flagged as low-signal — newer, less battle-tested entries.
+LOW_SIGNAL_COMMIT_COUNT = 2
+LOW_SIGNAL_AGE_DAYS = 30
+
+
+@dataclass
+class Command:
+    name: str
+    path: str
+    relpath: str
+    directory: str
+    description: str
+    aliases: List[str] = field(default_factory=list)
+    tier: int | None = None
+    cluster: str = ""
+    line_count: int = 0
+    last_modified_iso: str = ""
+    days_since_modified: int | None = None
+    commit_count: int = 0
+    first_commit_iso: str = ""
+    days_since_first_commit: int | None = None
+
+
+def parse_frontmatter(text: str) -> dict:
+    m = FRONTMATTER_RE.search(text)
+    if not m:
+        return {}
+    block = m.group(1)
+    out: dict = {}
+    if d := DESCRIPTION_RE.search(block):
+        out["description"] = d.group(1).strip()
+    if n := NAME_RE.search(block):
+        out["name"] = n.group(1).strip().strip('"').strip("'")
+    if c := CLUSTER_RE.search(block):
+        out["cluster"] = c.group(1).strip().strip('"').strip("'")
+    if t := TIER_RE.search(block):
+        out["tier"] = int(t.group(1))
+    if a := ALIASES_RE.search(block):
+        raw = a.group(1).strip()
+        if raw.startswith("["):
+            inner = raw.strip("[]")
+            out["aliases"] = [x.strip().strip('"').strip("'") for x in inner.split(",") if x.strip()]
+        else:
+            out["aliases"] = [raw.strip('"').strip("'")] if raw else []
+    return out
+
+
+def keyword_vector(text: str) -> Counter[str]:
+    tokens = re.findall(r"[a-z][a-z0-9_-]{2,}", text.lower())
+    return Counter(t for t in tokens if t not in STOPWORDS)
+
+
+def cosine(a: Counter[str], b: Counter[str]) -> float:
+    if not a or not b:
+        return 0.0
+    shared = set(a) & set(b)
+    if not shared:
+        return 0.0
+    num = sum(a[t] * b[t] for t in shared)
+    da = math.sqrt(sum(v * v for v in a.values()))
+    db = math.sqrt(sum(v * v for v in b.values()))
+    return num / (da * db) if da and db else 0.0
+
+
+def git_last_modified(path: Path) -> tuple[str, int | None]:
+    try:
+        out = subprocess.check_output(
+            ["git", "log", "--follow", "-1", "--format=%cI", "--", str(path)],
+            cwd=REPO_ROOT, stderr=subprocess.DEVNULL, text=True,
+        ).strip()
+        if not out:
+            return "", None
+        ts = datetime.fromisoformat(out)
+        days = (datetime.now(timezone.utc) - ts).days
+        return out, days
+    except (subprocess.CalledProcessError, ValueError):
+        return "", None
+
+
+def git_history(path: Path) -> tuple[int, str, int | None]:
+    """Return (commit_count, first_commit_iso, days_since_first_commit).
+
+    Uses ``--follow`` so renames (e.g. the ``.augment.uncompressed`` →
+    ``.agent-src.uncompressed`` rename) don't reset the per-file history.
+    """
+    try:
+        out = subprocess.check_output(
+            ["git", "log", "--follow", "--format=%cI", "--", str(path)],
+            cwd=REPO_ROOT, stderr=subprocess.DEVNULL, text=True,
+        ).strip().splitlines()
+        if not out:
+            return 0, "", None
+        first = out[-1]
+        ts = datetime.fromisoformat(first)
+        days = (datetime.now(timezone.utc) - ts).days
+        return len(out), first, days
+    except (subprocess.CalledProcessError, ValueError):
+        return 0, "", None
+
+
+def collect(root: Path) -> List[Command]:
+    commands: List[Command] = []
+    for md in sorted(root.rglob("*.md")):
+        if any(p == "_archive" for p in md.parts):
+            continue
+        text = md.read_text(encoding="utf-8")
+        fm = parse_frontmatter(text)
+        rel = md.relative_to(REPO_ROOT)
+        directory = str(md.parent.relative_to(root)) if md.parent != root else "."
+        last_iso, days = git_last_modified(md)
+        n_commits, first_iso, first_days = git_history(md)
+        commands.append(Command(
+            name=fm.get("name", md.stem),
+            path=str(md),
+            relpath=str(rel),
+            directory=directory,
+            description=fm.get("description", ""),
+            aliases=fm.get("aliases", []),
+            tier=fm.get("tier"),
+            cluster=fm.get("cluster", ""),
+            line_count=len(text.splitlines()),
+            last_modified_iso=last_iso,
+            days_since_modified=days,
+            commit_count=n_commits,
+            first_commit_iso=first_iso,
+            days_since_first_commit=first_days,
+        ))
+    return commands
+
+
+def find_overlap_pairs(commands: List[Command]) -> list[dict]:
+    vectors = {c.relpath: keyword_vector(c.description) for c in commands}
+    pairs: list[dict] = []
+    for a, b in combinations(commands, 2):
+        if not a.description or not b.description:
+            continue
+        sim = cosine(vectors[a.relpath], vectors[b.relpath])
+        if sim < OVERLAP_COSINE_THRESHOLD:
+            continue
+        pairs.append({
+            "a": a.relpath,
+            "b": b.relpath,
+            "a_name": a.name,
+            "b_name": b.name,
+            "cosine": round(sim, 3),
+            "a_description": a.description,
+            "b_description": b.description,
+        })
+    return sorted(pairs, key=lambda p: -p["cosine"])
+
+
+def render_md(commands: List[Command], pairs: list[dict]) -> str:
+    by_dir: dict[str, list[Command]] = {}
+    for c in commands:
+        by_dir.setdefault(c.directory, []).append(c)
+
+    low_signal = [
+        c for c in commands
+        if c.commit_count and c.commit_count <= LOW_SIGNAL_COMMIT_COUNT
+        and (c.days_since_first_commit or 0) <= LOW_SIGNAL_AGE_DAYS
+    ]
+
+    lines = [
+        "# Command-Surface Inventory",
+        "",
+        f"> Generated by `scripts/audit_command_surface.py`. "
+        f"Source: `.agent-src.uncompressed/commands/`.",
+        "",
+        "## Summary",
+        "",
+        f"- **Total commands:** {len(commands)}",
+        f"- **Top-level commands (directory `.`):** {len(by_dir.get('.', []))}",
+        f"- **Sub-cluster directories:** {len([d for d in by_dir if d != '.'])}",
+        f"- **Low-signal (≤{LOW_SIGNAL_COMMIT_COUNT} commits AND ≤{LOW_SIGNAL_AGE_DAYS}d old):** {len(low_signal)}",
+        f"- **Overlap pairs (cosine ≥ {OVERLAP_COSINE_THRESHOLD}):** {len(pairs)}",
+        "",
+        "## Per-directory counts",
+        "",
+        "| Directory | Count |",
+        "|---|---:|",
+    ]
+    for d in sorted(by_dir):
+        lines.append(f"| `{d}` | {len(by_dir[d])} |")
+    lines.append("")
+
+    lines += ["## Likely-overlapping pairs", ""]
+    if not pairs:
+        lines.append("_No pairs above threshold._")
+    else:
+        lines += [
+            "| # | A | B | cosine | A description | B description |",
+            "|---|---|---|---:|---|---|",
+        ]
+        for i, p in enumerate(pairs, 1):
+            lines.append(
+                f"| {i} | `{p['a_name']}` | `{p['b_name']}` | {p['cosine']:.2f} | "
+                f"{p['a_description']} | {p['b_description']} |"
+            )
+    lines.append("")
+
+    lines += [
+        "## Usage-signal note",
+        "",
+        "Per-command invocation telemetry is **not** available. Two surrogate signals "
+        "were considered:",
+        "",
+        "- **Filesystem mtime** — useless: `task sync` rewrites every file when the "
+        "  compressed and uncompressed trees are regenerated.",
+        "- **Git history (`--follow`)** — uninformative here: the `.agent-src.uncompressed/` "
+        "  directory is the result of a recent rename (`.augment.uncompressed/` → "
+        "  `.agent-src.uncompressed/`), so almost every file shows a single recent commit "
+        f"  on the current branch. {len(low_signal)} of {len(commands)} commands fall into the "
+        f"  ≤{LOW_SIGNAL_COMMIT_COUNT}-commits / ≤{LOW_SIGNAL_AGE_DAYS}d-old bucket purely as a "
+        "  rename artefact, not as a real cold-tail signal.",
+        "",
+        "**Implication for Phase 1 categorisation:** keep / merge / retire decisions must "
+        "be made on **intent** (description content, overlap with sibling commands, tier "
+        "placement, cluster fit) rather than usage data. The cosine-≥0.6 overlap "
+        "pairs above are the primary structural lever.",
+        "",
+    ]
+
+    lines += [
+        "## Three-bucket categorisation (Phase 1 Step 4)",
+        "",
+        "The keep / merge / retire verdict lives in "
+        "[`command-surface-synthesis.md`](command-surface-synthesis.md) — hand-curated "
+        "and **not** regenerated by this script. Headline: 109 keep · 0 merge · 0 retire. "
+        "Every overlap pair and retire candidate surfaced by the council turned out to "
+        "be an intentional structural pattern (scope ladder, union dispatcher, thin "
+        "alias, tier-gated specialist), not redundancy.",
+        "",
+    ]
+
+    lines += [
+        "## Full inventory",
+        "",
+        "Column `bucket` is left blank — the categorisation lives in "
+        "[`command-surface-synthesis.md`](command-surface-synthesis.md). Every command "
+        "in this table maps to `keep` unless named in that file's tables.",
+        "",
+        "| Name | Path | Tier | Cluster | Aliases | Lines | Commits | Age (d) | Bucket |",
+        "|---|---|---:|---|---|---:|---:|---:|---|",
+    ]
+    for c in sorted(commands, key=lambda c: c.relpath):
+        aliases = ", ".join(c.aliases) if c.aliases else "—"
+        tier = "—" if c.tier is None else str(c.tier)
+        cluster = c.cluster or "—"
+        age = "—" if c.days_since_first_commit is None else str(c.days_since_first_commit)
+        lines.append(
+            f"| `{c.name}` | `{c.relpath}` | {tier} | {cluster} | {aliases} | "
+            f"{c.line_count} | {c.commit_count} | {age} | |"
+        )
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", type=Path, default=DEFAULT_ROOT)
+    parser.add_argument("--quiet", action="store_true")
+    args = parser.parse_args()
+    if not args.root.exists():
+        print(f"error: {args.root} does not exist", file=sys.stderr)
+        return 2
+
+    REPORT_DIR.mkdir(parents=True, exist_ok=True)
+    commands = collect(args.root)
+    pairs = find_overlap_pairs(commands)
+
+    OUT_JSON.write_text(
+        json.dumps({
+            "total": len(commands),
+            "thresholds": {
+                "overlap_cosine": OVERLAP_COSINE_THRESHOLD,
+                "low_signal_commit_count": LOW_SIGNAL_COMMIT_COUNT,
+                "low_signal_age_days": LOW_SIGNAL_AGE_DAYS,
+            },
+            "commands": [asdict(c) for c in commands],
+            "overlap_pairs": pairs,
+        }, indent=2),
+        encoding="utf-8",
+    )
+    OUT_MD.write_text(render_md(commands, pairs), encoding="utf-8")
+
+    if not args.quiet:
+        print(f"✅  Audited {len(commands)} commands.")
+        print(f"   JSON: {OUT_JSON.relative_to(REPO_ROOT)}")
+        print(f"   MD:   {OUT_MD.relative_to(REPO_ROOT)}")
+        print(f"   Overlap pairs (cosine ≥ {OVERLAP_COSINE_THRESHOLD}): {len(pairs)}")
+        low_n = sum(
+            1 for c in commands
+            if c.commit_count and c.commit_count <= LOW_SIGNAL_COMMIT_COUNT
+            and (c.days_since_first_commit or 0) <= LOW_SIGNAL_AGE_DAYS
+        )
+        print(f"   Low-signal (≤{LOW_SIGNAL_COMMIT_COUNT} commits, ≤{LOW_SIGNAL_AGE_DAYS}d): {low_n}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_compressed_paths.py

@@ -58,10 +58,15 @@ _LINK_RE = re.compile(r'\[[^\]]*\]\(([^)#\s]+)(?:#[^)]*)?\)')
 # Body-link prefixes whose resolution is intentionally out of scope.
 # Council Decision 2 (2026-05-06): P3.1 was cancelled, so guideline links
 # under `.agent-src/rules/` cannot resolve in the projected tree. Copilot
-# suppression (P6) is the silencer for the noise.
+# suppression (P6) is the silencer for the noise. `docs/contracts/` shares
+# the same shape as `docs/guidelines/` — both live at repo root and the
+# rewriter collapses `../../docs/{contracts,guidelines}/...` to a
+# `../docs/...` form that cannot resolve under `.agent-src/`.
 UNCHECKED_LINK_PREFIXES = (
     "../docs/guidelines/",
     "../../docs/guidelines/",
+    "../docs/contracts/",
+    "../../docs/contracts/",
 )
 
 

package/scripts/check_council_layout.py

@@ -15,6 +15,11 @@ catches **misplacement**, not naming-conventions inside the dirs:
     (e.g. agents/council-question-foo.md, agents/.council-foo.md).
   - council-* files under any other subdirectory of agents/.
 
+`agents/audit-*/` directories are exempt — historical audit bundles
+are cohesive, checked-in narratives (the canonical council dirs are
+gitignored) and may legitimately include council-* artefacts as part
+of the audit's evidence trail.
+
 Failure modes are enforced by `.agent-src.uncompressed/skills/ai-council/SKILL.md`
 § "Output path convention".
 
@@ -40,6 +45,10 @@ CANONICAL_DIRS = {
     "council-responses": ".json",
     "council-sessions": ".json",
 }
+# Subdirectory prefixes whose contents are exempt from the layout check.
+# `audit-*/` covers historical audit bundles where council artefacts
+# form part of the documented evidence trail.
+EXEMPT_DIR_PREFIXES = ("audit-",)
 # A council artefact is a file whose name starts with `council-` or
 # `.council-`. This intentionally excludes roadmaps like
 # `road-to-ai-council.md` whose stem only contains the word "council".
@@ -79,6 +88,8 @@ def find_violations(root: Path) -> list[str]:
             continue  # already handled above
         if rel.parts[0] in CANONICAL_DIRS:
             continue
+        if rel.parts[0].startswith(EXEMPT_DIR_PREFIXES):
+            continue
         findings.append(
             f"{path}: council artefact in non-canonical directory "
             f"agents/{rel.parts[0]}/ — only council-questions/, "

package/scripts/ci_time_ratio.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""CI-time / local-edit-time ratio (council file 07, Phase 2.3).
+
+Samples the last N commits on a branch, classifies each by touched
+paths (doc / skill / test / meta / mixed), and computes:
+
+    ratio = ci_time / local_time
+
+where:
+- `local_time` = delta between author-date of the *previous* commit and
+  author-date of the current commit, capped at 60 min to filter breaks.
+- `ci_time`  = sum of GitHub Actions workflow durations for that commit
+  sha (via `gh run list --commit <sha>`).
+
+Threshold rule (Round-3 Sonnet protocol):
+- Median ratio > 5× for any frequent class → that class needs a cheaper tier
+- Median ratio < 3× across all classes      → structural overhead acceptable
+
+Output: human-readable table on stdout + JSON to
+`agents/reports/ci-time-ratio.json`.
+
+Usage:
+    python3 scripts/ci_time_ratio.py --limit 30
+    python3 scripts/ci_time_ratio.py --branch main --limit 30 --out path.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import statistics
+import subprocess
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_OUT = REPO_ROOT / "agents" / "reports" / "ci-time-ratio.json"
+
+LOCAL_TIME_CAP_S = 60 * 60          # cap a single edit window at 60 min
+THRESHOLD_FAIL = 5.0
+THRESHOLD_PASS = 3.0
+
+
+def run(cmd: list[str]) -> str:
+    return subprocess.check_output(cmd, cwd=REPO_ROOT, text=True)
+
+
+def list_commits(branch: str, limit: int) -> list[dict]:
+    out = run(["git", "log", branch, f"-n{limit + 1}",
+               "--format=%H\t%at\t%s"]).strip().splitlines()
+    rows = []
+    for line in out:
+        sha, ts, subject = line.split("\t", 2)
+        rows.append({"sha": sha, "timestamp": int(ts), "subject": subject})
+    return rows
+
+
+def classify(sha: str) -> str:
+    files = run(["git", "show", "--name-only", "--format=", sha]).strip().splitlines()
+    files = [f for f in files if f]
+    if not files:
+        return "empty"
+    doc = sum(1 for f in files if f.startswith("docs/") or f.endswith(".md"))
+    skill = sum(1 for f in files if "/skills/" in f or f.startswith(".agent-src.uncompressed/skills/"))
+    test = sum(1 for f in files if f.startswith("tests/") or "/tests/" in f)
+    meta = sum(1 for f in files if f.startswith(("Taskfile", "scripts/", ".github/", "pyproject", "package")))
+    total = len(files)
+    # Single-class dominance: 70% of touched files in one bucket
+    for label, n in [("skill", skill), ("test", test), ("doc", doc), ("meta", meta)]:
+        if n >= max(1, int(total * 0.7)):
+            return label
+    return "mixed"
+
+
+def ci_duration_for(sha: str) -> int | None:
+    """Total wall-clock seconds for all completed runs of this commit."""
+    try:
+        out = run(["gh", "run", "list", "--commit", sha, "--limit", "20",
+                   "--json", "createdAt,updatedAt,status,conclusion"])
+    except subprocess.CalledProcessError:
+        return None
+    runs = json.loads(out)
+    if not runs:
+        return None
+    durations = []
+    for r in runs:
+        if r.get("status") != "completed":
+            continue
+        from datetime import datetime
+        c = datetime.fromisoformat(r["createdAt"].replace("Z", "+00:00"))
+        u = datetime.fromisoformat(r["updatedAt"].replace("Z", "+00:00"))
+        durations.append((u - c).total_seconds())
+    if not durations:
+        return None
+    # Workflows run in parallel — wall-clock is the max, not the sum.
+    return int(max(durations))
+
+
+def collect(branch: str, limit: int) -> list[dict]:
+    commits = list_commits(branch, limit)
+    if len(commits) < 2:
+        return []
+    rows = []
+    for i in range(len(commits) - 1):
+        cur, prev = commits[i], commits[i + 1]
+        local_s = min(cur["timestamp"] - prev["timestamp"], LOCAL_TIME_CAP_S)
+        if local_s < 30:
+            continue
+        ci_s = ci_duration_for(cur["sha"])
+        if ci_s is None:
+            continue
+        cls = classify(cur["sha"])
+        rows.append({
+            "sha": cur["sha"][:10], "class": cls,
+            "local_s": local_s, "ci_s": ci_s,
+            "ratio": round(ci_s / local_s, 2) if local_s else None,
+            "subject": cur["subject"][:80],
+        })
+    return rows
+
+
+def summarise(rows: list[dict]) -> dict:
+    by_class: dict[str, list[float]] = defaultdict(list)
+    for r in rows:
+        if r["ratio"] is not None:
+            by_class[r["class"]].append(r["ratio"])
+    summary = {}
+    for cls, ratios in sorted(by_class.items()):
+        m = statistics.median(ratios)
+        if m > THRESHOLD_FAIL:
+            verdict = "optimise"
+        elif m < THRESHOLD_PASS:
+            verdict = "acceptable"
+        else:
+            verdict = "watch"
+        summary[cls] = {"n": len(ratios), "median": round(m, 2),
+                        "min": round(min(ratios), 2), "max": round(max(ratios), 2),
+                        "verdict": verdict}
+    all_ratios = [r["ratio"] for r in rows if r["ratio"] is not None]
+    overall = {"n": len(all_ratios),
+               "median": round(statistics.median(all_ratios), 2) if all_ratios else None,
+               "verdict": ("acceptable" if all_ratios and statistics.median(all_ratios) < THRESHOLD_PASS
+                          else "needs-review" if all_ratios else "no-data")}
+    return {"overall": overall, "by_class": summary}
+
+
+def main() -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("--branch", default="HEAD")
+    p.add_argument("--limit", type=int, default=30)
+    p.add_argument("--out", type=Path, default=DEFAULT_OUT)
+    args = p.parse_args()
+    rows = collect(args.branch, args.limit)
+    report = summarise(rows)
+    report["sample"] = rows
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_text(json.dumps(report, indent=2) + "\n")
+    print(f"✅  Wrote {args.out.relative_to(REPO_ROOT)}  (n={report['overall']['n']})")
+    ov = report["overall"]
+    print(f"   overall median ratio: {ov['median']}×  →  {ov['verdict']}")
+    for cls, s in report["by_class"].items():
+        print(f"   {cls:7}  n={s['n']:2}  median={s['median']:.2f}×  range=[{s['min']}–{s['max']}]  {s['verdict']}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())