@caddis/cli 0.4.34 → 0.4.36

package/bundles/antigravity-plugin/agents/code-reviewer.md

@@ -21,6 +21,10 @@ You are a principal engineer doing a focused code review. You read the change an
    - **Conventions** — per the project's `AGENTS.md` (typed boundaries, no absolute paths, no silent
      failures/logging, layering, framework idioms).
    - **Simplicity** — dead code, duplication, needless abstraction (YAGNI), clearer alternative.
+   - **Reuse** — flag new code that repeats an existing function, and a fix made at one caller
+     instead of the shared point. The rules:
+     Before writing new code, search for an existing function to reuse. Prefer the standard library or an installed package over new code or a new dependency.
+     Before changing a function, find all its callers. Fix the shared point, unless the callers need different behaviour.
 
 ## Severity
 - **blocking** — must fix before merge (bug, security hole, missing test for behavior change, broken

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.121",
+  "version": "1.3.123",
   "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_file_lock.py

@@ -0,0 +1,121 @@
+"""Portable advisory locks and atomic UTF-8 document writes.
+
+Callers that have an artifact root should pass ``root=``. The resolved target
+must stay within that root, including when a path component is a symlink.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import errno
+import math
+import os
+from pathlib import Path
+import stat
+import tempfile
+import time
+from typing import BinaryIO, Iterator
+
+if os.name == "nt":
+    import msvcrt
+else:
+    import fcntl
+
+
+def _destination(path: Path, root: Path | None) -> Path:
+    path = Path(path)
+    if ".." in path.parts:
+        raise ValueError("destination may not contain parent traversal")
+    resolved = path.resolve()
+    if root is not None and not resolved.is_relative_to(Path(root).resolve()):
+        raise ValueError("destination escapes artifact root")
+    if path.is_symlink():
+        raise ValueError("destination may not be a symlink")
+    return resolved
+
+
+def _document_mode(target: Path) -> int:
+    """Mode the replaced document should keep: the existing one, else what ``open()`` would give."""
+    try:
+        return stat.S_IMODE(target.stat().st_mode)
+    except FileNotFoundError:
+        # os.umask has no read-only form; the probe is process-wide for one line, so a file
+        # another thread creates in that window gets 0o666. caddis writers are single-threaded.
+        umask = os.umask(0)
+        os.umask(umask)
+        return 0o666 & ~umask
+
+
+def _try_lock(handle: BinaryIO) -> bool:
+    try:
+        if os.name == "nt":
+            handle.seek(0)
+            msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
+        else:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+        return True
+    except OSError as exc:
+        if exc.errno not in (errno.EACCES, errno.EAGAIN, errno.EDEADLK):
+            raise
+        return False
+
+
+def _unlock(handle: BinaryIO) -> None:
+    if os.name == "nt":
+        handle.seek(0)
+        msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+    else:
+        fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+
+
+@contextlib.contextmanager
+def locked_path(
+    path: Path, timeout_s: float = 5.0, *, root: Path | None = None
+) -> Iterator[Path]:
+    """Hold a stable adjacent lock for ``path``; never remove its inode."""
+    if not math.isfinite(timeout_s) or timeout_s < 0:
+        raise ValueError("timeout_s must be a finite nonnegative number")
+    target = _destination(path, root)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    lock_path = target.with_name(target.name + ".lock")
+    if lock_path.is_symlink():
+        raise ValueError("lock file may not be a symlink")
+    # O_NOFOLLOW closes the gap between the check above and the open on POSIX.
+    flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0)
+    deadline = time.monotonic() + timeout_s
+    with os.fdopen(os.open(lock_path, flags, 0o666), "r+b") as handle:
+        while not _try_lock(handle):
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError(f"timed out waiting for lock: {lock_path}")
+            time.sleep(min(0.05, remaining))
+        try:
+            yield target
+        finally:
+            _unlock(handle)
+
+
+def atomic_write(path: Path, text: str, *, root: Path | None = None) -> None:
+    """Atomically replace one document; hold ``locked_path`` for read/modify/write.
+
+    A failed write or replace removes only this call's temporary file.
+    """
+    target = _destination(path, root)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    temporary: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w", encoding="utf-8", newline="", dir=target.parent,
+            prefix=f".{target.name}.", suffix=".tmp", delete=False,
+        ) as handle:
+            temporary = Path(handle.name)
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        # NamedTemporaryFile creates 0o600; without this every write would narrow the document.
+        os.chmod(temporary, _document_mode(target))
+        os.replace(temporary, target)
+        temporary = None  # replaced: that name may now belong to another writer
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)

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

@@ -108,6 +108,18 @@ def parse(text: str) -> dict:
     return out
 
 
+def split_document(text: str) -> tuple[dict, str]:
+    """Return parsed metadata and the untouched body after a complete leading header."""
+    source = text.lstrip("\ufeff")
+    lines = source.splitlines(keepends=True)
+    if not lines or lines[0].strip() != "---":
+        return {}, text
+    for index, line in enumerate(lines[1:], 1):
+        if line.strip() == "---":
+            return parse(source), "".join(lines[index + 1:])
+    return {}, text
+
+
 def validate(text: str, allowed_types: set[str]) -> str | None:
     """Report the first missing or unsupported required header field."""
     if _header_lines(text) is None:

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

@@ -21,6 +21,9 @@ that hard-fails when it cannot read its inputs breaks every consumer the day it
 first thing anyone does with a gate that cries wolf is switch it off. Only a genuine, positively
 identified violation is non-zero.
 
+One exception: `deploy-boundary` guards the production boundary and FAILS CLOSED. When it
+cannot tell, it exits 3 ("could not run" on the caddis scale), never 0.
+
 EXIT CODES
   0  proceed
   1  blocked           — a real violation; the caller must stop
@@ -93,10 +96,11 @@ def phase_lane(block: str) -> str:
 def launch_command(block: str) -> str:
     """The literal command for a non-claude lane, if the phase names one.
 
-    Also matches a caddis_lanes.py run command for the codex, agy and glm lanes.
+    Also matches a caddis_lanes.py run command or a direct codex/agy command.
     """
     m = re.search(
-        r'`((?:claude-(?:glm|oss|deepseek)|' + _LANES_RUN + r')[^`]*)`',
+        r'`((?:claude-(?:glm|oss|deepseek)\b|' + _LANES_RUN
+        + r'\b|codex\s+exec\b|agy\b)[^`]*)`',
         block,
     )
     return m.group(1).strip() if m else ""
@@ -139,6 +143,28 @@ def gate_lane(plan: Path, phase: int) -> int:
                 f"[caddis-gate] phase {phase}'s caddis_lanes command names --phase {named.group(1)}: {cmd}\n"
                 "  The lane would run another phase's work. Refusing to run it.\n")
             return EXIT_MALFORMED
+    elif re.match(r"(?:codex\s+exec|agy)\b", cmd):
+        if "HEADLESS RUN RULES" not in cmd:
+            sys.stderr.write(
+                f"[caddis-gate] phase {phase}'s direct command has no HEADLESS RUN RULES: {cmd}\n"
+                "  The child has no headless run rules. Refusing to run it.\n")
+            return EXIT_MALFORMED
+        named = re.search(r"Implement Phase (\d+) only", cmd)
+        if not named:
+            sys.stderr.write(
+                f"[caddis-gate] phase {phase}'s direct command has no phase restriction: {cmd}\n"
+                "  The lane could run the wrong phase. Refusing to run it.\n")
+            return EXIT_MALFORMED
+        if int(named.group(1)) != phase:
+            sys.stderr.write(
+                f"[caddis-gate] phase {phase}'s direct command names Phase {named.group(1)}: {cmd}\n"
+                "  The lane would run another phase's work. Refusing to run it.\n")
+            return EXIT_MALFORMED
+        if cmd.startswith("agy") and not re.search(r"(?:^|\s)(?:-p|--print)(?:\s|$)", cmd):
+            sys.stderr.write(
+                f"[caddis-gate] phase {phase}'s direct agy command has no -p/--print: {cmd}\n"
+                "  The child would not run headless. Refusing to run it.\n")
+            return EXIT_MALFORMED
     elif not re.search(r"(?:^|\s)(?:-p|--print)(?:\s|$)", cmd):
         sys.stderr.write(
             f"[caddis-gate] phase {phase}'s launch command has no -p/--print: {cmd}\n"
@@ -440,7 +466,7 @@ def gate_vendor_drift(repo_root: Path) -> int:
 _DOC_PATH = re.compile(r"`([^`\s<>{}*?]+?\.(?:md|py|ts|tsx|json|ya?ml|sh|ps1|html|toml|sql))`")
 
 
-def gate_handover_check(doc: Path, repo_root: Path) -> int:
+def gate_handover_check(doc: Path, repo_root: Path, max_chars: int | None = None) -> int:
     """Every file a handover names must exist. Nothing else in a handover is machine-checkable.
 
     A succession prompt is written from memory, so it names files the writer BELIEVES are there.
@@ -454,8 +480,10 @@ def gate_handover_check(doc: Path, repo_root: Path) -> int:
     later withdrawal" — need conventions that do not exist yet, and a gate that pretends to check
     them would be worse than one that says it does not.
 
-    Degrades open on a missing/unreadable doc. Blocks only on a path the doc claims and the repo
-    does not have.
+    Degrades open on a missing/unreadable doc. Blocks on a path the doc claims and the repo does
+    not have, and -- only when the caller passes ``max_chars`` -- on a doc longer than that. The
+    cap is opt-in: /handoff caps a workstream relay at 4,000 characters, but a /spawn-hub prompt
+    must embed the full inventory verbatim and would never fit.
     """
     if not doc.is_file():
         return _degrade(f"no handover doc at {doc}")
@@ -464,6 +492,12 @@ def gate_handover_check(doc: Path, repo_root: Path) -> int:
     except OSError as exc:
         return _degrade(f"cannot read {doc}: {type(exc).__name__}")
 
+    if max_chars is not None and len(text) > max_chars:
+        sys.stderr.write(
+            f"[caddis-gate] handover doc {doc.name} exceeds {max_chars:,} characters ({len(text)} chars)\n"
+        )
+        return EXIT_BLOCKED
+
     missing: list[str] = []
     for raw in sorted(set(_DOC_PATH.findall(text))):
         # A backtick often wraps a whole command; the path is the token that looks like one.
@@ -617,6 +651,166 @@ def gate_docs_check(root: Path) -> int:
     return EXIT_BLOCKED if failures else EXIT_OK
 
 
+# ── gate: deploy-boundary ───────────────────────────────────────────────────
+# The owner's production boundary: an agent never merges into a repo whose default branch deploys
+# on every push. /ship, /ship-merge and /pr-merge run this before any merge or push to the default
+# branch, and hand the merge to the owner on anything but exit 0.
+#
+# FAILS CLOSED — the one deliberate exception to DEGRADE OPEN above. "Cannot tell" is exit 3,
+# never 0, because a false "clean" here is a production deploy nobody approved. Any positive
+# signal wins over every negative one: config cannot switch the check off.
+EXIT_CANNOT_TELL = 3
+
+_WORKFLOW_DIRS = (".github/workflows", ".gitea/workflows", ".forgejo/workflows")
+
+# An inherited GIT_DIR (from a hook or wrapper) would make `git -C <repo>` read another repository.
+_GIT_REPO_ENV = ("GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_OBJECT_DIRECTORY",
+                 "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_COMMON_DIR", "GIT_NAMESPACE")
+
+
+def _git_out(repo: Path, *args: str) -> str | None:
+    """stdout of a git command in `repo`, or None when it fails."""
+    env = {k: v for k, v in os.environ.items() if k not in _GIT_REPO_ENV}
+    try:
+        r = subprocess.run(["git", "-C", str(repo), *args], capture_output=True, text=True,
+                           encoding="utf-8", errors="replace", timeout=30, env=env)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return r.stdout if r.returncode == 0 else None
+
+
+def _ref_exists(repo: Path, ref: str) -> bool:
+    return _git_out(repo, "rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}") is not None
+
+
+def _default_branch_refs(repo: Path) -> list[str]:
+    """Every copy of the default branch: each remote's and the local branch of that name.
+
+    The name comes from any remote's recorded HEAD; with none recorded, `main` and `master` stand
+    in. Reading every copy is deliberate: a positive signal on any of them blocks.
+    """
+    remotes = (_git_out(repo, "remote") or "").split()
+    names: set[str] = set()
+    for remote in remotes:
+        target = (_git_out(repo, "symbolic-ref", "--quiet", f"refs/remotes/{remote}/HEAD") or "").strip()
+        if target.startswith(f"refs/remotes/{remote}/"):
+            names.add(target[len(f"refs/remotes/{remote}/"):])
+    names = names or {"main", "master"}
+    refs = [f"refs/remotes/{r}/{n}" for r in remotes for n in sorted(names)]
+    refs += [f"refs/heads/{n}" for n in sorted(names)]
+    return [r for r in refs if _ref_exists(repo, r)]
+
+
+def _config_production_on_main(text: str) -> bool | None:
+    """True/False from `[deploy] production_on_main`; None when absent. Raises on a bad file."""
+    import tomllib
+    deploy = tomllib.loads(text).get("deploy", {})
+    if not isinstance(deploy, dict):
+        raise ValueError("[deploy] is not a table")
+    value = deploy.get("production_on_main")
+    if value is not None and not isinstance(value, bool):
+        raise ValueError(f"production_on_main is {value!r}, not true or false")
+    return value
+
+
+# A deploy is often not named "deploy". Letters-only boundaries on prod, so `deploy_prod` matches
+# and `product` or `reproduce` do not.
+_DEPLOY_WORD = re.compile(r"deploy|release|publish|(?<![a-z])prod(?:uction)?(?![a-z])", re.I)
+
+
+def _workflow_deploys(text: str) -> bool:
+    """True when the workflow's name, a job id or a job name looks like a deploy, or a job sets a
+    GitHub `environment:` (the forge's own marker for a deployment). Raises on a bad file.
+
+    The caller also checks the file name: a forge shows the file path as the workflow's name when
+    `name:` is unset.
+    """
+    import yaml
+    doc = yaml.safe_load(text)
+    if not isinstance(doc, dict) or not isinstance(doc.get("jobs"), dict):
+        raise ValueError("not a workflow (no jobs mapping)")
+    labels = [doc.get("name")]
+    for job_id, job in doc["jobs"].items():
+        labels.append(job_id)
+        if isinstance(job, dict):
+            if job.get("environment"):
+                return True
+            labels.append(job.get("name"))
+    return any(_DEPLOY_WORD.search(str(label)) for label in labels if label is not None)
+
+
+def gate_deploy_boundary(repo: Path) -> int:
+    """EXIT_BLOCKED when a push to the default branch deploys to production, EXIT_OK when it
+    positively does not, EXIT_CANNOT_TELL otherwise."""
+    blocked: list[str] = []
+    unknown: list[str] = []
+
+    top = _git_out(repo, "rev-parse", "--show-toplevel") if repo.is_dir() else None
+    root = Path(top.strip()) if top else repo
+    refs = _default_branch_refs(root) if top else []
+    if not repo.is_dir():
+        unknown.append(f"{repo} is not a directory")
+    elif not top:
+        unknown.append(f"{repo} is not a git repository")
+    elif not refs:
+        unknown.append("cannot find the default branch (no remote HEAD, no main or master)")
+    # HEAD is what is about to be merged or pushed: a deploy it adds lands on the default branch.
+    # It only ever adds signals; the default branch is still read, so deleting there hides nothing.
+    sources = refs + (["HEAD"] if top and _ref_exists(root, "HEAD") else [])
+
+    # Config: the working tree and every source. Only `true` counts; config cannot switch it off.
+    configs: list[tuple[str, str | None]] = []
+    cfg = root / ".caddis" / "config.toml"
+    if cfg.is_file():
+        configs.append(("working tree", None))
+    for ref in sources:
+        text = _git_out(root, "show", f"{ref}:.caddis/config.toml")
+        if text is not None:
+            configs.append((ref, text))
+    for where, text in configs:
+        try:
+            if _config_production_on_main(cfg.read_text(encoding="utf-8") if text is None else text):
+                blocked.append(f".caddis/config.toml ({where}) sets production_on_main = true")
+        except Exception as exc:
+            unknown.append(f".caddis/config.toml ({where}) unreadable: {exc}")
+
+    # Workflows: read from committed trees, never the working tree.
+    for ref in sources:
+        listing = _git_out(root, "ls-tree", "-r", "-z", "--name-only", ref, "--", *_WORKFLOW_DIRS)
+        if listing is None:
+            unknown.append(f"cannot list workflows on {ref}")
+            continue
+        for path in listing.split("\0"):
+            # Forges run only the files directly inside the workflows directory.
+            if path.rsplit("/", 1)[0] not in _WORKFLOW_DIRS:
+                continue
+            if not path.lower().endswith((".yml", ".yaml")):
+                continue
+            text = _git_out(root, "show", f"{ref}:{path}")
+            try:
+                if text is None:
+                    raise OSError("git show failed")
+                if _DEPLOY_WORD.search(path.rsplit("/", 1)[1]) or _workflow_deploys(text):
+                    blocked.append(f"{path} on {ref} deploys")
+            except Exception as exc:
+                unknown.append(f"{path} on {ref} unreadable: {type(exc).__name__}: {exc}")
+
+    if blocked:
+        print("[gate] deploy-boundary: BLOCKED — a push to the default branch deploys to production")
+        for reason in dict.fromkeys(blocked):
+            print(f"    {reason}")
+        print("    Do not merge. Hand the merge to the owner with the PR link.")
+        return EXIT_BLOCKED
+    if unknown:
+        print("[gate] deploy-boundary: CANNOT TELL — treat as production")
+        for reason in dict.fromkeys(unknown):
+            print(f"    {reason}")
+        print("    Do not merge. Hand the merge to the owner with the PR link.")
+        return EXIT_CANNOT_TELL
+    print(f"[gate] deploy-boundary: clean — no deploy signal found on {', '.join(sources)}")
+    return EXIT_OK
+
+
 def main(argv: list[str] | None = None) -> int:
     ap = argparse.ArgumentParser(description="caddis machine gates")
     sub = ap.add_subparsers(dest="cmd", required=True)
@@ -640,11 +834,21 @@ def main(argv: list[str] | None = None) -> int:
     hc = sub.add_parser("handover-check")
     hc.add_argument("--doc", required=True)
     hc.add_argument("--repo-root", default=".")
+    hc.add_argument("--max-chars", type=int, default=None,
+                    help="block a doc longer than this (relays: 4000); default: no cap")
     dc = sub.add_parser("docs-check")
     dc.add_argument("--root", default=".")
+    db = sub.add_parser("deploy-boundary")
+    db.add_argument("--repo", default=".")
     a = ap.parse_args(argv)
 
     plan = Path(getattr(a, "plan", "") or ".")
+    if a.cmd == "deploy-boundary":
+        try:
+            return gate_deploy_boundary(Path(a.repo).resolve())
+        except Exception as exc:
+            sys.stderr.write(f"[caddis-gate] deploy-boundary cannot evaluate: {type(exc).__name__}: {exc}\n")
+            return EXIT_CANNOT_TELL  # never degrade open across the production boundary
     if a.cmd == "docs-check":
         try:
             return gate_docs_check(Path(a.root).resolve())
@@ -665,7 +869,7 @@ def main(argv: list[str] | None = None) -> int:
         if a.cmd == "vendor-drift":
             return gate_vendor_drift(Path(a.repo_root).resolve())
         if a.cmd == "handover-check":
-            return gate_handover_check(Path(a.doc), Path(a.repo_root).resolve())
+            return gate_handover_check(Path(a.doc), Path(a.repo_root).resolve(), a.max_chars)
         return gate_tracker(plan)
     except Exception as exc:  # pragma: no cover — a gate must never crash the caller
         return _degrade(f"{type(exc).__name__}: {exc}")

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

@@ -47,6 +47,14 @@ import sys
 from dataclasses import dataclass, field
 from pathlib import Path
 
+try:
+    import caddis_frontmatter
+except ModuleNotFoundError as exc:
+    if exc.name != "caddis_frontmatter":
+        raise
+    sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "claude-harness" / "scripts"))
+    import caddis_frontmatter
+
 if hasattr(sys.stdout, "reconfigure"):
     sys.stdout.reconfigure(encoding="utf-8", errors="replace")
 
@@ -71,15 +79,7 @@ def frontmatter(path: Path) -> dict[str, str]:
         text = path.read_text(encoding="utf-8", errors="ignore").lstrip("")
     except OSError:
         return {}
-    if not text.startswith("---"):
-        return {}
-    end = text.find("\n---", 3)
-    out: dict[str, str] = {}
-    for line in text[3:end if end > 0 else 800].splitlines():
-        if ":" in line and not line.startswith((" ", "\t")):
-            k, _, v = line.partition(":")
-            out[k.strip()] = v.strip()
-    return out
+    return caddis_frontmatter.parse(text)
 
 
 def title_of(path: Path) -> str: