@caddis/cli 0.4.74 → 0.4.76

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.160",
+  "version": "1.3.162",
   "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/scripts/caddis_coordinate.py

@@ -962,7 +962,10 @@ def session_lookup(sessions: list[dict], *, session_id: str | None = None, name:
 
 CONFIG_KEYS = ("schema", "default_branch", "merge_method", "required_checks", "not_required", "docs_only",
                "main_workflow", "reviews", "peer_ack", "deploy", "owner_reserved", "stall", "quiet")
-OPTIONAL_CONFIG_KEYS = ("relay",)  # the coordinator's own relay: `.caddis/relay/<relay>.md`
+OPTIONAL_CONFIG_KEYS = ("relay", "start_mode")  # relay: `.caddis/relay/<relay>.md`; start_mode: see START_MODES
+# The merge mode a start begins in. "target" in the reviewed, merged config is the owner's standing consent
+# for the coordinator to run `gh pr merge` (command section 2). Missing means "interim".
+START_MODES = ("interim", "target")
 CONFIG_SCHEMA = 1
 _PLACEHOLDER = "<fill:"
 _FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})[ \t]*([^\s`]*)")  # a Markdown code fence and its info string
@@ -1018,8 +1021,9 @@ def load_config(repo_root: Path) -> dict:
     """Read `<repo_root>/.caddis/coordinator.md` and return its json block.
 
     Raise FileNotFoundError when the file is missing, ValueError when there is no json block, a key is missing,
-    `schema` is not 1, a value is still a `<fill: ...>` placeholder, or the optional `relay` is not a plain
-    workstream name (`caddis_workstreams.is_plain_name`: lower case `a-z0-9_-`, no Windows device name)."""
+    `schema` is not 1, a value is still a `<fill: ...>` placeholder, the optional `relay` is not a plain
+    workstream name (`caddis_workstreams.is_plain_name`: lower case `a-z0-9_-`, no Windows device name), or the
+    optional `start_mode` is not one of START_MODES."""
     path = config_path(repo_root)
     try:
         text = path.read_text(encoding="utf-8")
@@ -1040,9 +1044,92 @@ def load_config(repo_root: Path) -> dict:
     if "relay" in config and not _plain_workstream_name(config["relay"]):
         raise ValueError(f"the config relay must be a plain workstream name such as coordinator, "
                          f"not {config['relay']!r}")
+    if "start_mode" in config and config["start_mode"] not in START_MODES:
+        raise ValueError(f"the config start_mode must be one of {', '.join(START_MODES)}, "
+                         f"not {config['start_mode']!r}")
     return config
 
 
+_CONFIG_REL = ".caddis/coordinator.md"
+
+
+def _start_mode_at(repo_root: Path, rev: str) -> str | None:
+    """`start_mode` in the config at `rev`: a mode, None (no file or no key) or "invalid"."""
+    shown = _run(["git", "-C", str(repo_root), "show", f"{rev}:{_CONFIG_REL}"])
+    if shown.returncode != 0:
+        return None
+    try:
+        block = _config_block(shown.stdout)
+    except ValueError:
+        return "invalid"
+    if not isinstance(block, dict):
+        return "invalid"
+    if "start_mode" not in block:
+        return None
+    return block["start_mode"] if block["start_mode"] in START_MODES else "invalid"
+
+
+def _origin_default_branch(repo_root: Path) -> str | None:
+    """The default branch from `refs/remotes/origin/HEAD`, never from the work tree (review, 24 Oct 2026)."""
+    out = _run(["git", "-C", str(repo_root), "symbolic-ref", "--short", "refs/remotes/origin/HEAD"])
+    ref = out.stdout.strip() if out.returncode == 0 else ""
+    return ref[len("origin/"):] if ref.startswith("origin/") and len(ref) > len("origin/") else None
+
+
+def _set_target_commit(repo_root: Path, ref: str) -> tuple[str | None, str | None]:
+    """The commit on `ref` where `start_mode` last became "target" (newest first: the oldest commit of the newest
+    unbroken run of target versions). The ledger cites it as the owner's consent."""
+    out = _run(["git", "-C", str(repo_root), "log", "--format=%H%x09%s", ref, "--", _CONFIG_REL])
+    if out.returncode != 0:
+        return None, None
+    found: tuple[str | None, str | None] = (None, None)
+    for line in out.stdout.splitlines():
+        sha, _, subject = line.partition("\t")
+        if _start_mode_at(repo_root, sha) != "target":
+            break
+        found = (sha, subject)
+    return found
+
+
+def config_mode(repo_root: Path) -> dict:
+    """The merge mode a start begins in. Target only when origin's default branch AND the work tree both say
+    `"start_mode": "target"`: the work tree of a shared checkout can hold an uncommitted edit that no owner
+    approved (review, 24 Oct 2026). The branch comes from `origin/HEAD`, not from the work-tree config; a work
+    tree whose `default_branch` differs is a mismatch. Returns mode, work_tree, origin, mismatch, set_by (the
+    commit that set target) and set_by_subject. Fetch first; a stale origin ref gives a stale answer."""
+    work = load_config(repo_root)
+    branch = _origin_default_branch(repo_root)
+    origin = _start_mode_at(repo_root, f"origin/{branch}") if branch else "invalid"
+    work_mode = work.get("start_mode")
+    set_by = set_by_subject = None
+    if origin == "target":
+        set_by, set_by_subject = _set_target_commit(repo_root, f"origin/{branch}")
+
+    def effective(value: str | None) -> str:  # missing means interim
+        return value or "interim"
+    mismatch = (origin == "invalid" or branch != work["default_branch"]
+                or effective(work_mode) != effective(origin))
+    mode = "target" if not mismatch and effective(origin) == "target" else "interim"
+    return {"mode": mode, "work_tree": work_mode, "origin": origin, "mismatch": mismatch,
+            "set_by": set_by, "set_by_subject": set_by_subject}
+
+
+def config_changed(diff: str) -> bool:
+    """True when a unified diff touches .caddis/coordinator.md in any way: add, delete, rename to or from it,
+    edit, binary or mode-only change. That file holds the coordinator's own rules (start_mode, required checks,
+    owner_reserved), so such a PR is owner-only (R4) in every mode. File-level on purpose: a text match on keys
+    can be dodged with JSON escapes (review, 24 Oct 2026)."""
+    marks = (f"+++ b/{_CONFIG_REL}", f"--- a/{_CONFIG_REL}", f"rename from {_CONFIG_REL}", f"rename to {_CONFIG_REL}",
+             f"copy from {_CONFIG_REL}", f"copy to {_CONFIG_REL}")
+    for line in diff.splitlines():
+        if line in marks:
+            return True
+        if line.startswith("diff --git ") and (line.startswith(f"diff --git a/{_CONFIG_REL} ")
+                                               or line.endswith(f" b/{_CONFIG_REL}")):
+            return True
+    return False
+
+
 def _plain_workstream_name(value: object) -> bool:
     """The relay name rule of `caddis_workstreams` (one rule, so a relay that loads here can also be read there)."""
     try:
@@ -1497,9 +1584,12 @@ def _parser() -> argparse.ArgumentParser:
     p.add_argument("--path", default=".", help="a folder inside the checkout (default: current folder)")
 
     config = sub.add_parser("config").add_subparsers(dest="config_command", required=True, parser_class=_Parser)
-    for name in ("show", "init"):
+    for name in ("show", "init", "mode"):
         p = command(name, config, repo=False)
         p.add_argument("--path", default=".", help="the repo root (default: current folder)")
+    p = command("pr-check", config, repo=False)
+    p.add_argument("--pr", type=int, required=True, help="the PR whose diff to check (`gh pr diff`)")
+    p.add_argument("--gh-repo", help="owner/name for `gh pr diff -R` (default: the current folder's repo)")
 
     p = command("session", repo=False)
     which = p.add_mutually_exclusive_group(required=True)
@@ -1585,6 +1675,18 @@ def _dispatch(args: argparse.Namespace) -> int:
         if args.config_command == "init":
             path = init_config(Path(args.path))
             _emit(args, {"path": str(path)}, str(path))
+        elif args.config_command == "mode":
+            got = config_mode(Path(args.path))
+            _emit(args, got, got["mode"] + (" (work tree and origin differ)" if got["mismatch"] else ""))
+        elif args.config_command == "pr-check":
+            cmd = ["gh", "pr", "diff", str(args.pr)] + (["-R", args.gh_repo] if args.gh_repo else [])
+            out = _run(cmd)
+            if out.returncode != 0:
+                raise ValueError(f"gh pr diff {args.pr} failed: {out.stderr.strip()[:200]}")
+            changed = config_changed(out.stdout)
+            _emit(args, {"pr": args.pr, "changes_config": changed},
+                  "owner-only: the PR changes .caddis/coordinator.md" if changed else "no coordinator config change")
+            return EXIT_LOCK_REFUSED if changed else EXIT_OK
         else:
             loaded = load_config(Path(args.path))
             _emit(args, loaded, json.dumps(loaded, indent=2))

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

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""Batched hub collector: every repo's roadmaps, plans and relays, plus agy spend and the guide, as one JSON object.
+
+Usage: caddis_hub_collect.py --repos PATH [PATH ...] [--only roadmaps,plans,relays,spend,guide] --json
+
+The hub runs this once per cycle. It runs in ONE Python process for all repos (hub rule R15, spawn cost L8). It
+never calls gh, claude or agy, and never runs `git fetch`: the roadmap reader sees the origin refs the repo
+already has. The parsers stay in the scripts that own each format (R14); this file only calls them.
+
+Output: {"schema": 1, "generated_at": "<UTC Z>", "repos": [{"path", "fingerprint", "roadmaps", "plans",
+"relays"}], "spend": ..., "guide": ...}. A path that is not a folder gives {"path", "error"}. A source that fails
+gives {"error": "<one line>"} in its slot. The run still exits 0. Exit 1 is for bad arguments only.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import importlib
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+SCHEMA = 1
+KINDS = ("roadmaps", "plans", "relays", "spend", "guide")
+_REPO_KINDS = ("roadmaps", "plans", "relays")
+
+
+def _sibling(name: str):
+    """A sibling script as a module. The same module object the rest of the process uses."""
+    try:
+        return importlib.import_module(name)
+    except ModuleNotFoundError as exc:
+        if exc.name != name:
+            raise
+        sys.path.insert(0, str(Path(__file__).resolve().parent))
+        return importlib.import_module(name)
+
+
+def _error(exc: BaseException) -> dict:
+    lines = str(exc).strip().splitlines()
+    return {"error": lines[0] if lines else type(exc).__name__}
+
+
+def _roadmaps_json(root: Path) -> dict:
+    module = _sibling("caddis_roadmap")
+    saved = module.FETCH
+    module.FETCH = False  # R15: no network git. Read the origin refs the repo already has.
+    try:
+        return module.roadmaps_json(root)
+    finally:
+        module.FETCH = saved
+
+
+def _plans_json(root: Path) -> dict:
+    return _sibling("caddis_todo").plans_json(root)
+
+
+def _relays_json(root: Path) -> dict:
+    return _sibling("caddis_workstreams").relays_json(root)
+
+
+def _spend_json() -> dict:
+    return _sibling("caddis_spend").spend_json(Path.home())
+
+
+def _guide_json() -> dict:
+    return _sibling("build_reference").guide_json()
+
+
+_REPO_COLLECTORS = {"roadmaps": _roadmaps_json, "plans": _plans_json, "relays": _relays_json}
+
+
+_REPARSE_POINT = 0x400  # FILE_ATTRIBUTE_REPARSE_POINT: a junction or a symlink on Windows
+
+
+def _is_link(path: Path) -> bool:
+    """True for a symlink or a Windows junction. Python 3.11 `is_symlink()` is False for a junction."""
+    try:
+        info = path.lstat()
+    except OSError:
+        return False  # not there: nothing to follow
+    return path.is_symlink() or bool(getattr(info, "st_file_attributes", 0) & _REPARSE_POINT)
+
+
+def _files(folder: Path, pattern: str = "*", recurse: bool = False) -> list[Path]:
+    """The plain files in `folder`. Never enter a linked folder and never list a linked file (stat only)."""
+    if not folder.is_dir() or _is_link(folder):
+        return []
+    found: list[Path] = []
+    for path in folder.iterdir():
+        if _is_link(path):
+            continue
+        if path.is_dir():
+            if recurse:
+                found.extend(_files(path, pattern, recurse))
+        elif path.is_file() and path.match(pattern):
+            found.append(path)
+    return found
+
+
+def _input_files(repo: Path) -> list[Path]:
+    """The files the repo's collectors read from the working tree."""
+    artifact = repo / ".caddis"
+    if _is_link(artifact):
+        return []
+    files = _files(artifact / "roadmaps", recurse=True)
+    plans = artifact / "plans"
+    if not plans.is_dir():
+        plans = repo / ".github" / "plans"  # the legacy folder, as caddis_todo reads it
+    files.extend(_files(plans, "*.md"))
+    files.extend(_files(artifact / "relay", "*.md"))
+    return files
+
+
+def git_common_dir(repo: Path) -> Path | None:
+    """The git common dir, found with no subprocess: a `.git` folder, or a `.git` file (a worktree) whose `gitdir:`
+    folder has a `commondir` file. None when the repo has no readable git dir."""
+    dot_git = repo / ".git"
+    if _is_link(dot_git):
+        return None
+    if dot_git.is_dir():
+        return dot_git
+    try:
+        line = dot_git.read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeDecodeError):
+        return None
+    if not line.startswith("gitdir:"):
+        return None
+    gitdir = Path(line[len("gitdir:"):].strip())
+    if not gitdir.is_absolute():
+        gitdir = repo / gitdir
+    try:
+        common = (gitdir / "commondir").read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeDecodeError):
+        return gitdir if gitdir.is_dir() else None
+    path = Path(common)
+    return path if path.is_absolute() else gitdir / path
+
+
+def _origin_ref_files(common: Path) -> list[Path]:
+    """The ref files the roadmap reader gets its data from: packed-refs, origin/HEAD, every origin branch."""
+    files = [p for p in (common / "packed-refs",) if p.is_file() and not _is_link(p)]
+    # refs/remotes/origin/HEAD sits inside refs/remotes/origin/, so the walk covers it.
+    return files + _files(common / "refs" / "remotes" / "origin", recurse=True)
+
+
+def fingerprint(repo: Path) -> str:
+    """sha256 over the sorted (name, mtime_ns, size) of every input file and origin ref file. Empty list: still a hash.
+
+    The roadmaps come from the origin refs (`git show origin/<default>:...`), so a fetch must change the hash."""
+    repo = Path(repo)
+    named = [(path.relative_to(repo).as_posix(), path) for path in _input_files(repo)]
+    common = git_common_dir(repo)
+    if common is not None:
+        named.extend((f"git:{path.relative_to(common).as_posix()}", path) for path in _origin_ref_files(common))
+    rows = []
+    for name, path in named:
+        try:
+            info = path.stat()
+        except OSError:
+            continue  # the file went away while we looked
+        rows.append((name, info.st_mtime_ns, info.st_size))
+    return hashlib.sha256(json.dumps(sorted(rows)).encode("utf-8")).hexdigest()
+
+
+def collect_repo(path: str, kinds: tuple[str, ...]) -> dict:
+    repo = Path(path)
+    if not repo.is_dir():
+        return {"path": path, "error": "not a folder"}
+    entry: dict = {"path": path}
+    try:
+        entry["fingerprint"] = fingerprint(repo)
+    except Exception as exc:  # a repo we cannot read must not stop the others
+        return {"path": path, **_error(exc)}
+    for kind in _REPO_KINDS:
+        if kind not in kinds:
+            continue
+        try:
+            entry[kind] = _REPO_COLLECTORS[kind](repo)
+        except Exception as exc:
+            entry[kind] = _error(exc)
+    return entry
+
+
+def collect(repos: list[str], kinds: tuple[str, ...]) -> dict:
+    out: dict = {"schema": SCHEMA, "generated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+                 "repos": [collect_repo(path, kinds) for path in repos]}
+    for kind, call in (("spend", _spend_json), ("guide", _guide_json)):
+        if kind not in kinds:
+            continue
+        try:
+            out[kind] = call()
+        except Exception as exc:
+            out[kind] = _error(exc)
+    return out
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str):  # bad arguments exit 1, not argparse's 2
+        self.print_usage(sys.stderr)
+        print(f"caddis-hub-collect: {message}", file=sys.stderr)
+        raise SystemExit(1)
+
+
+def main(argv: list[str] | None = None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8", errors="replace")
+    parser = _Parser(description=__doc__.splitlines()[0])
+    parser.add_argument("--repos", nargs="+", required=True, metavar="PATH")
+    parser.add_argument("--only", default=",".join(KINDS), help="comma list of: " + ", ".join(KINDS))
+    parser.add_argument("--json", action="store_true", required=True)
+    args = parser.parse_args(argv)
+    kinds = tuple(k.strip() for k in args.only.split(",") if k.strip())
+    unknown = [k for k in kinds if k not in KINDS]
+    if unknown or not kinds:
+        parser.error(f"unknown --only kind: {', '.join(unknown) or '(empty)'}; use {', '.join(KINDS)}")
+    print(json.dumps(collect(args.repos, kinds), ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -49,7 +49,8 @@ Exit codes (caddis_exit): 0 clean, 1 blocked (nothing ready, check failing, PR n
 (no origin, no roadmap, lock busy, an exit check or Exit setup that cannot run in the merged checkout), 4 error
 (malformed roadmap, unknown id, column or value, refused change).
 
-Usage: caddis_roadmap.py status --roadmap SLUG [--root DIR] [--json]
+Usage: caddis_roadmap.py list [--root DIR] [--json]
+       caddis_roadmap.py status --roadmap SLUG [--root DIR] [--json]
        caddis_roadmap.py next --roadmap SLUG [--root DIR] [--json]
        caddis_roadmap.py check --roadmap SLUG [--root DIR]
        caddis_roadmap.py set --roadmap SLUG [--root DIR] --id ID --col Status|Owner|Target --value V [--by-owner]
@@ -198,6 +199,9 @@ DROPPED_PREFIX = "dropped:"
 OLD_BLOCKER_DAYS = 14  # status lists a blocker whose row is older than this
 
 
+JSON_SCHEMA = 1  # the `schema` key of every --json output (hub rule R13)
+
+
 class RoadmapError(Exception):
     """A refused or impossible request; carries the caddis exit code."""
 
@@ -237,11 +241,21 @@ def _git(root: Path, *args: str, check: bool = True) -> subprocess.CompletedProc
 
 
 def default_branch(root: Path) -> str:
-    """origin/HEAD's branch; when it is not set locally, ask the remote (`git ls-remote --symref origin HEAD`)."""
+    """origin/HEAD's branch; when it is not set locally, ask the remote (`git ls-remote --symref origin HEAD`).
+    When FETCH is off, never ask the remote: use origin/main or origin/master if exactly one exists locally."""
     proc = _git(root, "symbolic-ref", "refs/remotes/origin/HEAD", check=False)
     ref = proc.stdout.strip()
     if proc.returncode == 0 and ref.startswith("refs/remotes/origin/"):
         return ref[len("refs/remotes/origin/"):]
+    if not FETCH:
+        # No network when fetch is off (the collector, `render --no-fetch`): use the one local origin branch.
+        found = [name for name in ("main", "master")
+                 if _git(root, "rev-parse", "--verify", "--quiet", f"refs/remotes/origin/{name}^{{commit}}",
+                         check=False).returncode == 0]
+        if len(found) == 1:
+            return found[0]
+        raise RoadmapError("cannot tell origin's default branch: origin/HEAD is not set locally; "
+                           "run: git remote set-head origin --auto", caddis_exit.NOT_RUN)
     remote = _git(root, "ls-remote", "--symref", "origin", "HEAD", check=False)
     for line in remote.stdout.splitlines():
         match = re.match(r"^ref:\s*refs/heads/(\S+)\s+HEAD$", line)
@@ -2190,6 +2204,19 @@ def list_roadmaps_checked(root: Path) -> tuple[list[str], set[str] | None]:
     return sorted(slugs), folders
 
 
+def roadmaps_json(root: Path) -> dict:
+    """The hub's roadmap list: status() of each slug, in `list` order. A roadmap whose status() raises gives
+    {"roadmap": slug, "error": "<one line>"} and the rest still list. Never prints, never exits."""
+    entries: list[dict] = []
+    for slug in list_roadmaps(Path(root)):
+        try:
+            entries.append(status(Path(root), slug))
+        except Exception as exc:  # one broken file must not hide the others
+            lines = str(exc).strip().splitlines()
+            entries.append({"roadmap": slug, "error": lines[0] if lines else type(exc).__name__})
+    return {"schema": JSON_SCHEMA, "roadmaps": entries}
+
+
 def _build_parser() -> argparse.ArgumentParser:
     parser = _Parser(description=__doc__.splitlines()[0])
     sub = parser.add_subparsers(dest="cmd", required=True)
@@ -2206,6 +2233,7 @@ def _build_parser() -> argparse.ArgumentParser:
 
     p = sub.add_parser("list")
     p.add_argument("--root", default=".")
+    p.add_argument("--json", action="store_true")
     add("status", json_out=True)
     add("next", json_out=True)
     add("check")
@@ -2371,6 +2399,10 @@ def _render_site(root: Path, args: argparse.Namespace) -> int:
 
 def _dispatch(args: argparse.Namespace) -> int:
     root = _repo_root(args.root)
+    if args.cmd == "list" and args.json:
+        data = roadmaps_json(root)
+        print(json.dumps(data, indent=2))
+        return caddis_exit.CLEAN if data["roadmaps"] else caddis_exit.BLOCKED
     if args.cmd == "list":
         slugs = list_roadmaps(root)
         for slug in slugs:
@@ -2378,12 +2410,13 @@ def _dispatch(args: argparse.Namespace) -> int:
         return caddis_exit.CLEAN if slugs else caddis_exit.BLOCKED
     if args.cmd == "status":
         result = status(root, args.roadmap)
-        print(json.dumps(result, indent=2) if args.json else result["line"])
+        print(json.dumps({"schema": JSON_SCHEMA, **result}, indent=2) if args.json else result["line"])
         return caddis_exit.CLEAN
     if args.cmd == "next":
         batch, reasons = _select(load(root, args.roadmap), other_roadmap_batches(root, args.roadmap))
         if args.json:
-            print(json.dumps({"batch": batch, "skipped": [{"id": i, "reason": r} for i, r in reasons]}))
+            skipped = [{"id": i, "reason": r} for i, r in reasons]
+            print(json.dumps({"schema": JSON_SCHEMA, "batch": batch, "skipped": skipped}))
         else:
             for mid, reason in reasons:
                 print(f"{mid}: {reason}")

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

@@ -493,6 +493,19 @@ def status_line(home: Path, now: datetime) -> str:
     return f"agy: EUR {committed_last_24h(home, now):.2f} of {cap} in the last 24 h on this machine"
 
 
+def spend_json(home: Path, now: datetime | None = None) -> dict:
+    """The spend status as one JSON-ready dict. It holds no key, no prompt and no caller name."""
+    now = now or datetime.now(timezone.utc)
+    try:
+        cap = load_cap(home)
+        cap_eur, reserve_eur = float(cap.eur_per_24h), float(cap.reserve)
+    except NotConfigured:
+        cap_eur = reserve_eur = None
+    return {"schema": 1, "configured": cap_eur is not None, "cap_eur": cap_eur,
+            "committed_eur": round(committed_last_24h(home, now), 6), "reserve_eur": reserve_eur,
+            "window_h": 24}
+
+
 def main(argv: list[str] | None = None) -> int:
     if hasattr(sys.stdout, "reconfigure"):
         sys.stdout.reconfigure(encoding="utf-8", errors="replace")
@@ -504,7 +517,8 @@ def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description="global agy spend cap (EUR per rolling 24 h, this machine)")
     sub = parser.add_subparsers(dest="cmd", required=True)
     sub.add_parser("check")
-    sub.add_parser("status")
+    p_status = sub.add_parser("status")
+    p_status.add_argument("--json", action="store_true", help="print the status as one JSON object")
     p_run = sub.add_parser("run")
     p_run.add_argument("--caller", required=True)
     p_run.add_argument("--timeout-s", type=float, default=None,
@@ -515,7 +529,7 @@ def main(argv: list[str] | None = None) -> int:
     now = datetime.now(timezone.utc)
     if args.cmd == "status":
         try:
-            print(status_line(home, now))
+            print(json.dumps(spend_json(home, now)) if args.json else status_line(home, now))
         except Exception as exc:
             print(f"caddis_spend: could not read the spend log: {exc!r}", file=sys.stderr)
             return EXIT_NOT_CONFIGURED

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

@@ -9,6 +9,7 @@ release as a no-op, because an older /handoff still calls it from its Step 6.
 from __future__ import annotations
 
 import argparse
+import json
 import os
 import re
 import subprocess
@@ -17,7 +18,7 @@ from pathlib import Path
 
 try:
     import caddis_exit
-    from caddis_frontmatter import parse
+    from caddis_frontmatter import parse, split_document
     from caddis_workstreams import _artifact, _name
 except ModuleNotFoundError as exc:
     if exc.name not in {"caddis_exit", "caddis_file_lock", "caddis_frontmatter", "caddis_workstreams"}:
@@ -26,7 +27,7 @@ except ModuleNotFoundError as exc:
     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
-    from caddis_frontmatter import parse
+    from caddis_frontmatter import parse, split_document
     from caddis_workstreams import _artifact, _name
 
 
@@ -172,6 +173,63 @@ def tracker_table(text: str) -> tuple[list[str], list[str]] | None:
     return columns, table[:at] + table[at + 1:]
 
 
+def _plan_files(root: Path) -> list[Path]:
+    """The plan files to list: `.caddis/plans/*.md`, else the legacy `.github/plans/*.md`. Never `done/`."""
+    plans_dir = _artifact(root) / "plans"
+    if not plans_dir.is_dir():
+        plans_dir = Path(root) / ".github" / "plans"
+    if plans_dir.is_symlink() or not plans_dir.is_dir():
+        return []
+    return sorted(p for p in plans_dir.glob("*.md") if p.is_file() and not p.is_symlink())
+
+
+def _plan_entry(root: Path, path: Path) -> dict:
+    # caddis_tidy imports this module at load time, so this module imports it only here.
+    try:
+        import caddis_tidy
+    except ModuleNotFoundError as exc:
+        if exc.name != "caddis_tidy":
+            raise
+        sys.path.insert(0, str(Path(__file__).resolve().parent))
+        import caddis_tidy
+    text = path.read_text(encoding="utf-8")
+    meta, body = split_document(text)
+    if text.lstrip("").startswith("---") and not meta:
+        raise ValueError("frontmatter is not closed or has no keys")
+    heading = re.search(r"^# (.+?)\s*$", body, re.M)
+    title = heading.group(1) if heading else meta.get("title")
+    tracker: list[dict] = []
+    table = tracker_table(text)
+    if table is not None:
+        columns, lines = table
+        status_at = columns.index("status")
+        for line in lines:
+            if not line.strip().startswith("|") or caddis_tidy._TABLE_RULE_RE.match(line.strip()):
+                continue
+            cells = caddis_tidy._row_cells(line)
+            if cells:
+                tracker.append({"phase": cells[0], "status": cells[status_at] if len(cells) > status_at else ""})
+    return {"path": path.relative_to(Path(root)).as_posix(), "title": title,
+            "status": meta.get("status"), "feature": meta.get("feature"),
+            "tracker": tracker, "open_rows": sum(1 for row in tracker if not _is_done(row["status"]))}
+
+
+def plans_json(root: Path) -> dict:
+    """Every current plan as data: `{"schema": 1, "plans": [...]}`. Never prints, never exits.
+
+    A file that does not parse gives `{"path", "error"}`; the other plans still come back.
+    """
+    root = Path(root)
+    plans: list[dict] = []
+    for path in _plan_files(root):
+        try:
+            plans.append(_plan_entry(root, path))
+        except Exception as exc:  # one bad file must not hide the others
+            rel = path.relative_to(root).as_posix()
+            plans.append({"path": rel, "error": (str(exc).splitlines() or [type(exc).__name__])[0]})
+    return {"schema": 1, "plans": plans}
+
+
 def main(argv: list[str] | None = None) -> int:
     # Plan paths may carry non-ASCII text; a Windows console defaults to a legacy code page.
     for stream in (sys.stdout, sys.stderr):
@@ -181,6 +239,10 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--root", type=Path, default=Path.cwd(), help=argparse.SUPPRESS)
     commands = parser.add_subparsers(dest="command", required=True)
     commands.add_parser("active-plan")
+    plans_p = commands.add_parser("plans", help="list the plans as JSON")
+    plans_p.add_argument("--json", action="store_true", dest="as_json")
+    # `plans --root R` works too. SUPPRESS: when absent here, the global --root (or cwd) stays.
+    plans_p.add_argument("--root", type=Path, default=argparse.SUPPRESS, help="the project folder")
     # Retired: kept one release so an older /handoff Step 6 does not fail. Takes its old flag, ignores it.
     reconcile_p = commands.add_parser("reconcile", help=argparse.SUPPRESS)
     reconcile_p.add_argument("--session-state", type=Path)
@@ -190,6 +252,15 @@ def main(argv: list[str] | None = None) -> int:
     if args.command == "reconcile":
         print(RECONCILE_RETIRED)
         return 0
+    if args.command == "plans":
+        if not args.as_json:
+            parser.error("plans needs --json")
+        try:
+            print(json.dumps(plans_json(args.root), ensure_ascii=False))
+        except (OSError, ValueError) as exc:  # a .caddis that escapes the project
+            print(f"caddis-todo: {exc}", file=sys.stderr)
+            return 1
+        return 0
     try:
         plan, candidates = active_plan(args.root)
     except (OSError, UnicodeError, ValueError) as exc: