@caddis/cli 0.4.52 → 0.4.54

package/bundles/antigravity-plugin/CADDIS-GLOSSARY.md

@@ -126,6 +126,7 @@ plain word gets them wrong. Usage counts were measured across 444 markdown files
 | model lane | A named provider route reached by its own binary — `claude-oss`, `claude-glm`, `claude-deepseek` — all speaking the Anthropic protocol. A lane is a route, not a model. | provider, backend, endpoint |
 | core / extras | The two shipping tiers. Core is an EXPLICIT allowlist in `.github/runtime-targets.json`; anything not named there lands in extras. A skill defaults to extras, so placement is a decision, never an accident. | tier 1 / tier 2, full / lite |
 | harness | The agent runtime that loads caddis — Claude Code, agy, Codex, Copilot. caddis is agent-agnostic; "the harness" without a name means whichever one is running. *(135 uses)* | client, IDE, platform |
+| card | One full unit of work handed to a lane or a reviewer: scope, files and pass criteria, kept in a roadmap's cards/ folder. | task file, ticket |
 
 ## Flagged ambiguities
 

package/bundles/antigravity-plugin/guard_agy.py

@@ -32,6 +32,7 @@ from __future__ import annotations
 import json
 import os
 import re
+import shlex
 import sys
 
 # Functional identity, mirrored from scripts/claudster_config.py.
@@ -87,6 +88,187 @@ _CATASTROPHIC_TARGET = re.compile(
 _FORK_BOMB = re.compile(r":\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:")
 
 
+# `git add` of everything. A tokenizer, not a regex: three regex rounds each opened a new gap, and one backtracked
+# exponentially. Linear in the command length. Copied from hooks/guard.py; test_guard_agy.py checks they agree.
+_GA_SEPARATORS = {";", "&", "&&", "|", "||", "(", ")", "{", "}", "$", "!", "\n"}
+_GA_PUNCT = set(";&|(){}$!\n")  # a token made only of these is a separator (`$(`, `&&`, `);`, `|!`)
+_GA_KEYWORDS = {"if", "then", "else", "elif", "do", "while", "until"}  # the next word starts a command
+_GA_WRAPPERS = {"sudo", "command", "env", "exec", "nohup", "time", "timeout", "nice", "xargs", "call", "wsl",
+                "busybox"}
+_GA_SHELLS = {"bash", "sh", "zsh", "dash", "pwsh", "powershell", "cmd"}
+_GA_JOINING_SHELLS = {"cmd", "pwsh", "powershell"}  # they run ALL the words after the flag; bash -c runs one
+_GA_SHELL_RUN_FLAGS = {"-c", "/c", "/k", "-command", "-commandwithargs"}
+_GA_GIT_VALUE_OPTS = {"-c", "-C", "--git-dir", "--work-tree", "--namespace", "--super-prefix", "--config-env"}
+_GA_EVERYTHING = {"-A", "--all", ".", "./", ".\\", ":/", "*"}
+
+
+def _ga_sep(token: str) -> bool:
+    """A command separator: one of _GA_SEPARATORS, or a token made only of their characters (`$(`, `|!`)."""
+    return token in _GA_SEPARATORS or (bool(token) and set(token) <= _GA_PUNCT)
+
+
+def _ga_name(token: str) -> str:
+    """`/usr/bin/git`, `"C:\\Program Files\\Git\\cmd\\git.exe"`, `GIT` -> `git`."""
+    base = re.split(r"[\\/]", token)[-1].lower()
+    return base[:-4] if base.endswith(".exe") else base
+
+
+def _ga_tokens(text: str) -> list[str]:
+    """Shell tokens, quotes removed (also mid-token: --work-tree="my dir"), backslashes kept (Windows paths).
+    ; & | ( ) { } $ ! and newlines become separator tokens."""
+    def lex(quotes: str) -> list[str]:
+        lexer = shlex.shlex(text.replace("`", "\n"), posix=True, punctuation_chars=";&|(){}$!\n")
+        lexer.whitespace, lexer.whitespace_split, lexer.escape, lexer.quotes = " \t\r", True, "", quotes
+        return list(lexer)
+    try:
+        return lex("'\"")
+    except ValueError:  # unbalanced quotes: read it again without quote handling
+        return lex("")
+
+
+def git_add_everything(command: str, depth: int = 0) -> bool:
+    """True when `command` runs `git add` with -A/--all (also bundled, e.g. -Av), `.`, `./`, `:/` or `*`.
+
+    `git` must start a command (after a separator, a shell keyword such as `do`, VAR=value, or a wrapper such as
+    sudo, env, xargs, nice -n 10), with any path, case or .exe. `bash -c "..."`, `pwsh -Command ...` and
+    `cmd /c ...` are read inside. Only git's global options may stand between `git` and `add`, so
+    `git commit -m "add ."` and `printf "git add ."` pass. Callers pass heredoc-free text and must treat an
+    exception as "no match": this check must never stop the guard's other rules.
+    """
+    if depth > 3:
+        return False
+    text = re.sub(r"\\\r?\n|`\r?\n", " ", command)  # line continuations (bash \, PowerShell `)
+    tokens = _ga_tokens(text)
+    i, start = 0, True
+    while i < len(tokens):
+        tok = tokens[i]
+        if _ga_sep(tok):
+            i, start = i + 1, True
+            continue
+        if not start:
+            i += 1
+            continue
+        if tok in _GA_KEYWORDS or re.match(r"^\w+=", tok):  # `do git ...`, VAR=value before the command
+            i += 1
+            continue
+        name = _ga_name(tok)
+        if name in _GA_WRAPPERS:  # skip the wrapper's own flags and values up to the real command
+            i += 1
+            while i < len(tokens) and not _ga_sep(tokens[i]) and _ga_name(tokens[i]) not in ({"git"} | _GA_SHELLS):
+                i += 1
+            continue
+        start = False
+        if name in _GA_SHELLS:
+            j = i + 1
+            while j < len(tokens) and not _ga_sep(tokens[j]):
+                if tokens[j].lower() in _GA_SHELL_RUN_FLAGS:
+                    rest = tokens[j + 1:]
+                    end = next((k for k, t in enumerate(rest) if _ga_sep(t)), len(rest))
+                    if end == 0:  # `bash -c` with nothing after it
+                        break
+                    inner = " ".join(rest[:end]) if name in _GA_JOINING_SHELLS else rest[0]
+                    if git_add_everything(inner, depth + 1):
+                        return True
+                    break
+                j += 1
+            i = j
+            continue
+        if name != "git":
+            i += 1
+            continue
+        j = i + 1
+        while j < len(tokens) and tokens[j].startswith("-") and not _ga_sep(tokens[j]):
+            j += 2 if tokens[j] in _GA_GIT_VALUE_OPTS else 1
+        if j >= len(tokens) or tokens[j] != "add":
+            i = j
+            continue
+        after_dashdash = False
+        for arg in tokens[j + 1:]:
+            if _ga_sep(arg):
+                break
+            if arg == "--":
+                after_dashdash = True
+                continue
+            if after_dashdash and arg.startswith("-"):  # `git add -- -A` names a file called -A
+                continue
+            if arg in _GA_EVERYTHING or re.fullmatch(r"-[a-zA-Z]*A[a-zA-Z]*", arg):
+                return True
+        i = j + 1
+    return False
+
+
+# Copied from hooks/guard.py: a heredoc body that only carries data is not a command.
+_HEREDOC_MARKER = re.compile(
+    r"<<(-?)[ \t]*(?:'([A-Za-z_][A-Za-z_0-9]*)'|\"([A-Za-z_][A-Za-z_0-9]*)\"|([A-Za-z_][A-Za-z_0-9]*))"
+)
+_HEREDOC_INTERPRETER = re.compile(
+    r"^\s*(?:\S*/)?(?:bash|sh|zsh|dash|python|python3|py|node|ruby|perl|pwsh|powershell)\b",
+    re.I,
+)
+
+
+def _unquoted_at(line: str, position: int) -> bool:
+    """Whether a token at position is outside single and double quotes on this line."""
+    quote = ""
+    escaped = False
+    for char in line[:position]:
+        if escaped:
+            escaped = False
+        elif char == "\\" and quote != "'":
+            escaped = True
+        elif quote:
+            if char == quote:
+                quote = ""
+        elif char in "'\"":
+            quote = char
+    return not quote and not escaped
+
+
+def _without_heredoc_bodies(command: str) -> str:
+    """Skip complete data-only heredocs; preserve executable and incomplete bodies."""
+    lines = command.splitlines(keepends=True)
+    kept: list[str] = []
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        markers = []
+        executable = False
+        for marker in _HEREDOC_MARKER.finditer(line):
+            pos = marker.start()
+            if (pos and not (line[pos - 1].isspace() or line[pos - 1] in ";&|")
+                    or not _unquoted_at(line, pos)):
+                continue
+            markers.append((next(group for group in marker.groups()[1:] if group is not None),
+                            marker.group(1) == "-"))
+            owner = re.split(r"[;&|]", line[:pos])[-1]
+            executable |= bool(_HEREDOC_INTERPRETER.match(owner))
+        if not markers:
+            kept.append(line)
+            i += 1
+            continue
+        end = i
+        for tag, strip_tabs in markers:
+            end += 1
+            while end < len(lines):
+                candidate = lines[end].rstrip("\r\n")
+                if (candidate.lstrip("\t") if strip_tabs else candidate) == tag:
+                    break
+                end += 1
+            if end == len(lines):
+                return command
+        kept.extend(lines[i:end + 1] if executable else [line])
+        i = end + 1
+    return "".join(kept)
+
+
+def _git_add_everything_safe(text: str) -> bool:
+    """git_add_everything, but an error is "no match": one rule must never switch off the rest of the guard."""
+    try:
+        return git_add_everything(text)
+    except Exception:  # noqa: BLE001 - fail open for this rule only; the other rules still run
+        return False
+
+
 def _strip_quotes(s: str) -> str:
     """Drop quotes so quoted flags/targets still match (rm '-rf' \"/\" → rm -rf /)."""
     return s.replace('"', "").replace("'", "")
@@ -191,6 +373,8 @@ def classify_bash(command: str) -> tuple[str, str]:
         return "deny", "fork bomb"
     if re.search(r"\bdd\b.*\bof=/dev/", nl) or re.search(r"\bmkfs", nl) or re.search(r">\s*/dev/sd[a-z]", nl):
         return "deny", "writes directly to a disk device"
+    if _git_add_everything_safe(_without_heredoc_bodies(c)):
+        return "deny", "git add of everything (-A, --all, . or :/): stage named files only"
 
     # ── ask: destructive-but-legit ──
     if rm_rf:

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.138",
+  "version": "1.3.140",
   "description": "caddis — agent-agnostic dev harness as an Antigravity (agy) plugin: TDD skills + commands, single-sourced with the Claude Code plugin."
 }

package/bundles/antigravity-plugin/repo_freshness.py

@@ -24,10 +24,22 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import subprocess
 import sys
 import time
 
+try:
+    _cfg_scripts = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "scripts")
+    if _cfg_scripts not in sys.path:
+        sys.path.insert(0, _cfg_scripts)
+    from claudster_config import ARTIFACT_DIRS, artifact_root  # noqa: E402
+except Exception:  # pragma: no cover — defensive; a hook must never crash a session start
+    ARTIFACT_DIRS = (".caddis",)
+
+    def artifact_root(root):
+        return os.path.join(str(root), ARTIFACT_DIRS[0])
+
 # A narrow Windows console (cp1252) must not raise on a branch name with any Unicode in it.
 _reconfig = getattr(sys.stdout, "reconfigure", None)
 if _reconfig:
@@ -38,6 +50,7 @@ if _reconfig:
 
 FETCH_TIMEOUT_S = 15        # ceiling: a slow or unreachable remote must not stall a session
 FETCH_MAX_AGE_S = 600       # a restart within 10 minutes reuses the last fetch
+PEER_FRESH_S = 1800         # live peer session-state threshold (30 minutes, matches inject_relay)
 STAMP_NAME = "caddis-freshness-stamp"
 
 
@@ -83,7 +96,112 @@ def _count(cwd: str, rev_range: str) -> int:
     return int(out) if code == 0 and out.isdigit() else 0
 
 
-def report(cwd: str) -> list[str]:
+def _norm_path(raw: str) -> str:
+    """One path for comparison: no backticks, forward slashes, no leading `./`."""
+    norm = raw.strip().replace("`", "").strip().replace("\\", "/")
+    while norm.startswith("./"):
+        norm = norm[2:]
+    return norm
+
+
+def _status_entries(top: str) -> list[list[str]]:
+    """`git status --porcelain -z` at the repo top: one list of paths per entry (a rename gives two).
+    NUL-separated, so a path is never quoted. [] when git fails."""
+    try:
+        r = subprocess.run(["git", "status", "--porcelain", "-z"], cwd=top, capture_output=True, timeout=15)
+    except (OSError, subprocess.SubprocessError):
+        return []
+    if r.returncode != 0:
+        return []
+    parts = (r.stdout or b"").decode("utf-8", errors="replace").split("\0")
+    entries: list[list[str]] = []
+    i = 0
+    while i < len(parts):
+        entry = parts[i]
+        i += 1
+        if len(entry) < 4:
+            continue
+        paths = [entry[3:]]
+        if ("R" in entry[:2] or "C" in entry[:2]) and i < len(parts):
+            paths.append(parts[i])
+            i += 1
+        entries.append(paths)
+    return entries
+
+
+def _parse_session_state(text: str) -> tuple[str, list[str]]:
+    m = re.search(r"\*\*Branch:\*\*\s*`?([^\s`·]+)`?", text)
+    branch = m.group(1).strip() if m else "unknown"
+    files: list[str] = []
+    in_files = False
+    for line in text.splitlines():
+        s = line.strip()
+        if s.startswith("## "):
+            in_files = (s == "## Files changed this session")
+            continue
+        if in_files and s.startswith("- "):
+            item = s[2:].strip()
+            if item and not item.startswith("_("):
+                item = _norm_path(item)
+                if item:
+                    files.append(item)
+    return branch, files
+
+
+def _dirty_owners(top: str, dirty_paths: set[str], own_session_id: str = "") -> list[str]:
+    """Live peer sessions whose recorded files are dirty here. `top` is the repo top level: the
+    session-state folder and every path are read from there, whatever the session's cwd is."""
+    try:
+        if not dirty_paths:
+            return []
+        base = os.path.join(artifact_root(top), "session-state")
+        if not os.path.isdir(base):
+            legacy = os.path.join(top, ".claudster", "session-state")
+            if os.path.isdir(legacy):
+                base = legacy
+            else:
+                return []
+        now = time.time()
+        owners: list[str] = []
+        for name in sorted(os.listdir(base)):
+            try:
+                if not name.endswith(".md"):
+                    continue
+                sid = name[:-3]
+                if own_session_id and sid == own_session_id:
+                    continue
+                path = os.path.join(base, name)
+                mtime = os.path.getmtime(path)
+                if now - mtime > PEER_FRESH_S:
+                    continue
+                ended = os.path.join(base, sid + ".ended")
+                try:
+                    if os.path.getmtime(ended) >= mtime:
+                        continue
+                except OSError:
+                    pass
+                with open(path, encoding="utf-8", errors="replace") as fh:
+                    text = fh.read()
+                peer_branch, peer_files = _parse_session_state(text)
+                matched = False
+                for pf in peer_files:
+                    if pf in dirty_paths or any(
+                        dp.endswith("/") and pf.startswith(dp) for dp in dirty_paths
+                    ):
+                        matched = True
+                        break
+                if matched:
+                    label = f"owned by session {sid[:8]} (branch {peer_branch})"
+                    if label not in owners:
+                        owners.append(label)
+            except Exception:
+                continue
+        return owners
+    except Exception:
+        return []
+
+
+def report(cwd: str, own_session_id: str = "") -> list[str]:
     """The lines to print. Empty when there is nothing worth saying."""
     if _git(cwd, "rev-parse", "--is-inside-work-tree")[0] != 0:
         return []                                   # not a git repository
@@ -102,7 +220,11 @@ def report(cwd: str) -> list[str]:
             lines.append("[HARNESS] could not fetch origin - the figures below may be stale.")
 
     ref = _default_ref(cwd) if has_origin else ""
-    dirty = len([ln for ln in _git(cwd, "status", "--porcelain")[1].splitlines() if ln.strip()])
+    # The repo top level, so a session started in a subfolder still finds `.caddis/session-state`.
+    top = _git(cwd, "rev-parse", "--show-toplevel")[1] or cwd
+    entries = _status_entries(top)
+    dirty = len(entries)
+    dirty_paths = {_norm_path(p) for paths in entries for p in paths if _norm_path(p)}
     behind = _count(cwd, f"HEAD..{ref}") if ref else 0
     ahead = _count(cwd, f"{ref}..HEAD") if ref else 0
     default_branch = ref.split("/", 1)[-1] if ref else ""
@@ -112,8 +234,12 @@ def report(cwd: str) -> list[str]:
         lines.append(f"[HARNESS] branch '{branch}' | {behind} behind {ref} | {ahead} ahead "
                      f"| {dirty} uncommitted")
     if dirty:
-        lines.append("[HARNESS] There are uncommitted changes here. They may not be yours - these "
-                     "checkouts are shared. Look before you touch: git status")
+        msg = ("[HARNESS] There are uncommitted changes here. They may not be yours - these "
+               "checkouts are shared. Look before you touch: git status")
+        owners = _dirty_owners(top, dirty_paths, own_session_id=own_session_id)
+        if owners:
+            msg = f"{msg} ({'; '.join(owners)})"
+        lines.append(msg)
     # The recommendation, only when following it can lose nothing: behind, clean, and with
     # nothing of your own unpushed. Suggesting a branch switch to someone holding uncommitted
     # work in a shared checkout is how the branch-switch hazard gets triggered.
@@ -134,8 +260,9 @@ def main() -> int:
     except Exception:
         payload = {}
     cwd = (payload.get("cwd") if isinstance(payload, dict) else None) or os.getcwd()
+    session_id = (payload.get("session_id") if isinstance(payload, dict) else None) or ""
     try:
-        for line in report(cwd):
+        for line in report(cwd, own_session_id=str(session_id)):
             print(line)
     except Exception:
         pass          # fail open: a freshness report must never break a session start

package/bundles/antigravity-plugin/scripts/caddis_budget.py

@@ -0,0 +1,283 @@
+"""Growth control: size budgets and archive rules for handoff-grown files."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import re
+import sys
+from typing import NamedTuple
+
+try:
+    import caddis_exit
+except ModuleNotFoundError as exc:
+    if exc.name != "caddis_exit":
+        raise
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+    sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "claude-harness" / "scripts"))
+    import caddis_exit
+
+
+class Budget(NamedTuple):
+    glob: str
+    unit: str
+    limit: int
+    rule: str
+
+
+class Over(NamedTuple):
+    path: str
+    unit: str
+    value: int
+    limit: int
+    rule: str
+
+
+BUDGETS: tuple[Budget, ...] = (
+    Budget(
+        ".caddis/relay/*.md",
+        "chars",
+        4000,
+        "rewrite: current state only, git keeps history",
+    ),
+    Budget(
+        ".caddis/relay/*.tasks.md",
+        "table rows",
+        40,
+        "done rows are never written (Phase 1)",
+    ),
+    Budget(
+        ".caddis/relay.md",
+        "lines",
+        60,
+        "rendered by render-index; drop relays with status closed",
+    ),
+    Budget(
+        ".caddis/open-work.md",
+        "rows with Status done",
+        10,
+        "move done rows to .caddis/done/open-work-archive.md with a one-line pointer",
+    ),
+    Budget(
+        "DECISIONS.md, .caddis/DECISIONS.md, .caddis/decisions/DECISIONS.md",  # the last is the fleet's real path
+        "History table rows",
+        30,
+        "move older rows to DECISIONS-archive.md beside it",
+    ),
+    Budget(
+        ".caddis/usage-log.jsonl",
+        "bytes",
+        5000000,
+        "rotate to usage-log-<YYYYMM>.jsonl",
+    ),
+    Budget(
+        ".caddis/session-state/*.md",
+        "files",
+        8,
+        "session_state.py prune (not in a shared checkout)",
+    ),
+    Budget(
+        ".caddis/kb/*.md",
+        "lines per file",
+        300,
+        "split, or move closed parts to .caddis/kb/done/",
+    ),
+)
+
+
+class _ParsedTable(NamedTuple):
+    heading: str | None
+    columns: list[str]
+    data_rows: list[list[str]]
+
+
+def _split_cells(line: str) -> list[str]:
+    s = line.strip()
+    if not s:
+        return []
+    parts = re.split(r"(?<!\\)\|", s)
+    if parts and parts[0] == "":
+        parts.pop(0)
+    if parts and parts[-1] == "":
+        parts.pop(-1)
+    return [p.strip() for p in parts]
+
+
+def _is_separator(line: str) -> bool:
+    cells = _split_cells(line)
+    if not cells:
+        return False
+    for cell in cells:
+        c = cell.strip()
+        if not c or any(ch not in "-: " for ch in c) or "-" not in c:
+            return False
+    return True
+
+
+def _parse_tables(text: str) -> tuple[list[_ParsedTable], int]:
+    lines = text.splitlines()
+    tables: list[_ParsedTable] = []
+    loose_rows = 0
+    n = len(lines)
+    i = 0
+    while i < n:
+        if lines[i].lstrip().startswith("|"):
+            run_start = i
+            while i < n and lines[i].lstrip().startswith("|"):
+                i += 1
+            run = lines[run_start:i]
+            if len(run) >= 2 and _is_separator(run[1]):
+                heading: str | None = None
+                for k in range(run_start - 1, -1, -1):
+                    s = lines[k].strip()
+                    if s.startswith("#"):
+                        heading = s.lstrip("#").strip()
+                        break
+                columns = _split_cells(run[0])
+                data_rows = [_split_cells(r) for r in run[2:] if not _is_separator(r)]
+                tables.append(_ParsedTable(heading=heading, columns=columns, data_rows=data_rows))
+            else:
+                for r in run:
+                    if not _is_separator(r) and not r.lstrip().startswith(("| Old #", "| # |")):
+                        loose_rows += 1
+        else:
+            i += 1
+    return tables, loose_rows
+
+
+def _count_table_rows(text: str) -> int:
+    tables, loose_rows = _parse_tables(text)
+    return sum(len(t.data_rows) for t in tables) + loose_rows
+
+
+def _norm_status(cell: str) -> str:
+    return cell.replace("**", "").replace("__", "").replace("`", "").strip().lower()
+
+
+def _count_done_rows(text: str) -> int:
+    tables, _ = _parse_tables(text)
+    done_re = re.compile(r"^done\b")
+    count = 0
+    if tables:
+        for t in tables:
+            col_map = {c.lower(): idx for idx, c in enumerate(t.columns)}
+            if "status" in col_map:
+                s_idx = col_map["status"]
+                for row in t.data_rows:
+                    if len(row) > s_idx and done_re.search(_norm_status(row[s_idx])):
+                        count += 1
+            else:
+                for row in t.data_rows:
+                    if any(_norm_status(c) == "done" for c in row):
+                        count += 1
+        return count
+
+    for line in text.splitlines():
+        if line.lstrip().startswith("|") and not _is_separator(line):
+            cells = _split_cells(line)
+            if any(_norm_status(c) == "done" for c in cells):
+                count += 1
+    return count
+
+
+def _count_history_rows(text: str) -> int:
+    tables, loose_rows = _parse_tables(text)
+    history_tables = [t for t in tables if t.heading and "history" in t.heading.lower()]
+    if history_tables:
+        return sum(len(t.data_rows) for t in history_tables)
+    return sum(len(t.data_rows) for t in tables) + loose_rows
+
+
+def _measure_file(path: Path, unit: str) -> int:
+    if unit == "bytes":
+        return path.stat().st_size
+    text = path.read_text(encoding="utf-8", errors="ignore")
+    if unit == "chars":
+        return len(text)
+    if unit == "table rows":
+        return _count_table_rows(text)
+    if unit in ("lines", "lines per file"):
+        return len(text.splitlines())
+    if unit == "rows with Status done":
+        return _count_done_rows(text)
+    if unit == "History table rows":
+        return _count_history_rows(text)
+    raise ValueError(f"unknown budget unit: {unit}")
+
+
+def check(root: Path) -> list[Over]:
+    """Return every file under ``root`` that exceeds its configured size budget."""
+    root = Path(root)
+    overs: list[Over] = []
+
+    for budget in BUDGETS:
+        if budget.unit == "files":
+            files = [p for p in sorted(root.glob(budget.glob)) if p.is_file()]
+            value = len(files)
+            if value > budget.limit:
+                overs.append(Over(budget.glob, budget.unit, value, budget.limit, budget.rule))
+            continue
+
+        patterns = [g.strip() for g in budget.glob.split(",")]
+        for pattern in patterns:
+            if "*" in pattern:
+                candidates = [p for p in sorted(root.glob(pattern)) if p.is_file()]
+            else:
+                candidate = root / pattern
+                candidates = [candidate] if candidate.is_file() else []
+
+            for p in candidates:
+                if pattern == ".caddis/relay/*.md" and p.name.endswith(".tasks.md"):
+                    continue
+                rel = p.relative_to(root).as_posix()
+                value = _measure_file(p, budget.unit)
+                if value > budget.limit:
+                    overs.append(Over(rel, budget.unit, value, budget.limit, budget.rule))
+
+    return overs
+
+
+def main(argv: list[str] | None = None) -> int:
+    if sys.stdout and hasattr(sys.stdout, "reconfigure"):
+        try:
+            sys.stdout.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+    if sys.stderr and hasattr(sys.stderr, "reconfigure"):
+        try:
+            sys.stderr.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+
+    parser = argparse.ArgumentParser(
+        prog="caddis_budget.py",
+        description="Check handoff-grown files against their size budgets.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    p_check = sub.add_parser("check", help="Check files under --root against BUDGETS.")
+    p_check.add_argument("--root", type=Path, default=Path("."), help="Repository root.")
+    p_check.add_argument(
+        "--report",
+        action="store_true",
+        help="Report files over budget but always exit 0.",
+    )
+
+    args = parser.parse_args(argv)
+    try:
+        overs = check(args.root)
+    except OSError as exc:  # a locked or unreadable file (Windows): --report still never fails the caller
+        print(f"[BUDGET] could not read every file: {exc}")
+        return caddis_exit.CLEAN if args.report else caddis_exit.NOT_RUN
+    if not overs:
+        print("[BUDGET] all within budget")
+        return caddis_exit.CLEAN
+
+    for over in overs:
+        print(f"OVER {over.path}: {over.value} {over.unit} > {over.limit}; fix: {over.rule}")
+    if args.report:
+        return caddis_exit.CLEAN
+    return caddis_exit.BLOCKED
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())