@caddis/cli 0.4.6 → 0.4.8

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.93",
+  "version": "1.3.95",
   "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_gate.py

@@ -480,6 +480,107 @@ def gate_handover_check(doc: Path, repo_root: Path) -> int:
     return EXIT_BLOCKED
 
 
+# ── cross-review trigger ────────────────────────────────────────────────────────────────────
+# serve-sight shipped FOUR production releases in one day, sixteen fixes across SQL, caches,
+# refresh jobs and React. `/caddis:cross-review` ran ZERO times. Not because it was broken:
+# `oss_review.py --check-config` reported it ready with two providers keyed. Nothing called it.
+#
+# Measured there: 4 of 39 plan files mention cross-review, and all four are /feature-plan outputs,
+# because that command writes the line into the plan template it emits. So planned feature work
+# got reviewed and a bug batch did not — REVIEW COVERAGE INVERSELY CORRELATED WITH URGENCY.
+#
+# Two of that day's sixteen fixes were diff-visible defects: a cache whose docstring said "cached
+# for the instance's life" while a FastAPI dependency rebuilt the object per request, so the cache
+# was never once read (5.03s per call, and the docstring described the bug while reading as a
+# design note); and two endpoints with no cache at all on a page with a 1s standard.
+#
+# Every rule below is checkable from `git diff --name-only` plus a line count. NO JUDGEMENT — that
+# is the point, because judgement is exactly what failed. Prose in a command would be one more
+# thing to remember, and 008 section 2 is this repo's record of a rule that lived only in a
+# document and lost to the artefact.
+REVIEW_BIG_DIFF_LINES = 400
+
+# (label, why, path-segment needles). Matched against lowercased POSIX path segments and the file
+# stem, never a bare substring of the whole path — `services` must be a directory or a filename
+# part, so `deprecated_services_notes.md` matches and `microservices-README` in a docs tree does
+# not sneak in through a parent directory nobody meant.
+REVIEW_TRIGGERS = [
+    ("sql", "where a wrong number is born — presence is not correctness",
+     ("sql", "queries", "query", "repositories", "repository", "migrations", "migration")),
+    ("services", "the layer the 2026-08-31 cache defects lived in, with no SQL in the diff",
+     ("services", "service")),
+    ("caching", "hit twice in one day at serve-sight",
+     ("cache", "caches", "caching", "refresh", "memo", "memoize")),
+    ("auth", "a mistake here is a breach, not a bug",
+     ("auth", "rbac", "permission", "permissions", "role", "roles", "authz", "authn")),
+]
+
+
+def _changed(repo_root: Path, rev_range: str | None) -> tuple[list[str], int]:
+    """(paths, changed-line-count) for the working tree, or for an explicit range."""
+    args = ["git", "-C", str(repo_root), "diff", "--numstat"]
+    if rev_range:
+        args.append(rev_range)
+    out = subprocess.run(args, capture_output=True, text=True, timeout=30).stdout
+    paths, lines = [], 0
+    for row in out.splitlines():
+        parts = row.split("	")
+        if len(parts) != 3:
+            continue
+        add, dele, path = parts
+        paths.append(path.strip())
+        for n in (add, dele):
+            if n.isdigit():
+                lines += int(n)
+    return paths, lines
+
+
+def review_triggers(paths: list[str], changed_lines: int) -> list[tuple[str, str, list[str]]]:
+    """[(label, why, matching paths)] — empty means the diff does not warrant a second opinion."""
+    fired: list[tuple[str, str, list[str]]] = []
+    for label, why, needles in REVIEW_TRIGGERS:
+        hits = []
+        for p in paths:
+            segs = [seg.lower() for seg in p.replace("\\", "/").split("/")]
+            stem = segs[-1].rsplit(".", 1)[0] if segs else ""
+            parts = set(segs[:-1]) | set(stem.replace("-", "_").split("_")) | {stem}
+            # `.sql` belongs to the sql rule ONLY. Left in the shared condition it made every
+            # trigger fire on any .sql file, so one migration reported sql+services+caching+auth
+            # and the reason column became noise.
+            if parts & set(needles) or (label == "sql" and segs[-1].endswith(".sql")):
+                hits.append(p)
+        if hits:
+            fired.append((label, why, sorted(hits)))
+    if changed_lines > REVIEW_BIG_DIFF_LINES:
+        fired.append(("size", f"{changed_lines} changed lines — size alone stops being reviewable",
+                      []))
+    return fired
+
+
+def gate_review_trigger(repo_root: Path, rev_range: str | None = None) -> int:
+    """EXIT_NOTE when the diff warrants cross-review, EXIT_OK when it does not.
+
+    NOTE, never BLOCKED. This decides when to ASK for a second opinion; it is not itself a verdict
+    and must not stop a ship. The honest limit, from the item that raised it: a trigger does not
+    make the review good, it makes it happen — and on the measured evidence that was the binding
+    constraint, with a configured, capable tool idle through sixteen chances to use it.
+    """
+    paths, changed = _changed(repo_root, rev_range)
+    if not paths:
+        print("[gate] review-trigger: empty diff — nothing to review")
+        return EXIT_OK
+    fired = review_triggers(paths, changed)
+    if not fired:
+        print(f"[gate] review-trigger: {len(paths)} file(s), {changed} line(s) — no trigger")
+        return EXIT_OK
+    print(f"[gate] review-trigger: RUN CROSS-REVIEW — {len(paths)} file(s), {changed} line(s)")
+    for label, why, hits in fired:
+        shown = ", ".join(hits[:4]) + (", ..." if len(hits) > 4 else "")
+        print(f"    {label}: {why}" + (f"{chr(10)}      {shown}" if hits else ""))
+    print("    /caddis:cross-review   (or: python .github/tools/oss_review.py)")
+    return EXIT_NOTE
+
+
 def main(argv: list[str] | None = None) -> int:
     ap = argparse.ArgumentParser(description="caddis machine gates")
     sub = ap.add_subparsers(dest="cmd", required=True)
@@ -494,6 +595,10 @@ def main(argv: list[str] | None = None) -> int:
     h.add_argument("--refs", nargs="*", default=[])
     pl = sub.add_parser("parking-lot")
     pl.add_argument("--repo-root", default=".")
+    rt = sub.add_parser("review-trigger")
+    rt.add_argument("--repo-root", default=".")
+    rt.add_argument("--range", dest="rev_range", default=None,
+                    help="revision range, e.g. origin/main...HEAD (default: the working tree)")
     vd = sub.add_parser("vendor-drift")
     vd.add_argument("--repo-root", default=".")
     hc = sub.add_parser("handover-check")
@@ -511,6 +616,8 @@ def main(argv: list[str] | None = None) -> int:
             return gate_hub_artifacts(Path(a.reports), [Path(r) for r in a.refs])
         if a.cmd == "parking-lot":
             return gate_parking_lot(Path(a.repo_root).resolve())
+        if a.cmd == "review-trigger":
+            return gate_review_trigger(Path(a.repo_root).resolve(), a.rev_range)
         if a.cmd == "vendor-drift":
             return gate_vendor_drift(Path(a.repo_root).resolve())
         if a.cmd == "handover-check":

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

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""Find the caddis SOURCE checkout from anywhere, so friction can be parked where it belongs.
+
+Almost every insight about the harness is noticed while NOT working on the harness — a session in
+an app repo hits friction and is in the wrong place to do anything about it. Today's options are
+all bad: park it locally where the maintainer never looks, say it in chat where it dies with the
+session, switch repos mid-task (nobody does), or remember it later (this is the one that actually
+happens, and later is usually never).
+
+So harness improvement is whatever someone recalls at the end of a session. The observations that
+survive are not a random sample: small, frequent friction — the kind that would most improve daily
+use — is exactly what does not survive, because it is not dramatic enough to recall.
+
+This resolves the target so `/caddis:park --harness` is a flag rather than a context switch.
+
+NOT the installed plugin. `CLAUDE_PLUGIN_ROOT` points at a read-only copy that is replaced on
+every update; an item written there is gone at the next `claude plugin update`. The maintainer
+works in the source checkout, so that is what this finds.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+EXIT_OK, EXIT_NOT_FOUND = 0, 1
+
+ENV_VAR = "CADDIS_HARNESS_ROOT"
+POINTER = Path.home() / ".caddis" / "harness-root"
+
+# A source checkout has BOTH of these. The installed plugin has neither pair, and an app repo
+# scaffolded by caddis has `.caddis/parking-lot/` but no `claude-harness/` — which is the
+# distinction that matters, because writing into an app repo is the exact failure to avoid.
+SIGNATURE = ("claude-harness", os.path.join(".caddis", "parking-lot"))
+
+
+def looks_like_harness(path: Path) -> bool:
+    try:
+        return all((path / part).is_dir() for part in SIGNATURE)
+    except OSError:
+        return False
+
+
+def resolve_harness_root(cwd: Path | None = None,
+                         env: dict | None = None,
+                         pointer: Path | None = None) -> tuple[Path | None, str]:
+    """(path, how-it-was-found) or (None, why-not).
+
+    Order is deliberate: an explicit answer beats a remembered one, and a remembered one beats a
+    guess. The search is last and is deliberately narrow.
+    """
+    env = os.environ if env is None else env
+    pointer = POINTER if pointer is None else pointer
+
+    raw = (env.get(ENV_VAR) or "").strip()
+    if raw:
+        p = Path(raw).expanduser()
+        if looks_like_harness(p):
+            return p, f"{ENV_VAR}"
+        return None, (f"{ENV_VAR} is set to {raw!r}, which is not a caddis source checkout "
+                      f"(needs both {SIGNATURE[0]}/ and {SIGNATURE[1]}/). Fix or unset it — an "
+                      "explicit setting is never silently ignored.")
+
+    try:
+        noted = pointer.read_text(encoding="utf-8").strip()
+    except OSError:
+        noted = ""
+    if noted:
+        p = Path(noted).expanduser()
+        if looks_like_harness(p):
+            return p, str(pointer)
+        return None, (f"{pointer} points at {noted!r}, which is no longer a caddis source "
+                      "checkout. Re-run with --set <path>.")
+
+    # Last resort: siblings of the current repo, then siblings of its parent. Every project on a
+    # given machine tends to live under one or two roots, so the checkout is usually a sibling of
+    # whatever repo noticed the friction. Deliberately shallow — a filesystem-wide search would
+    # be slow and would eventually find a stale clone.
+    start = (cwd or Path.cwd()).resolve()
+    seen: set[Path] = set()
+    for base in (start, *start.parents):
+        parent = base.parent
+        if parent in seen or parent == base:
+            continue
+        seen.add(parent)
+        try:
+            candidates = sorted(d for d in parent.iterdir() if d.is_dir())
+        except OSError:
+            continue
+        for d in candidates:
+            if looks_like_harness(d):
+                return d, f"found beside {base.name}"
+        if len(seen) >= 3:
+            break
+
+    return None, ("no caddis source checkout found. Set it once and it is remembered:"
+                  f"{os.linesep}    python caddis_harness_path.py --set <path-to-checkout>"
+                  f"{os.linesep}  or export {ENV_VAR}. NOT the installed plugin — an item written "
+                  "there is discarded by the next `claude plugin update`.")
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--set", dest="set_to", default=None,
+                    help="remember this path as the caddis source checkout")
+    ap.add_argument("--cwd", default=".", help="resolve as if from here")
+    a = ap.parse_args(argv)
+
+    if a.set_to:
+        p = Path(a.set_to).expanduser().resolve()
+        if not looks_like_harness(p):
+            sys.stderr.write(f"[harness] {p} is not a caddis source checkout — needs both "
+                             f"{SIGNATURE[0]}/ and {SIGNATURE[1]}/{os.linesep}")
+            return EXIT_NOT_FOUND
+        POINTER.parent.mkdir(parents=True, exist_ok=True)
+        POINTER.write_text(str(p) + "\n", encoding="utf-8")
+        print(f"[harness] remembered {p} in {POINTER}")
+        return EXIT_OK
+
+    root, how = resolve_harness_root(Path(a.cwd).resolve())
+    if root is None:
+        # FAIL LOUDLY. Silently writing into the local repo is the failure this exists to prevent:
+        # the item would sit in an app repo the maintainer never reads, which is the status quo.
+        sys.stderr.write("[harness] " + how + os.linesep)
+        return EXIT_NOT_FOUND
+    print(str(root))
+    return EXIT_OK
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -501,7 +501,8 @@ def _handshake_path(repo_root: Path, spawn_id: str) -> Path:
     return repo_root / SPAWN_DIR / (spawn_id + "-handshake.json")
 
 
-def handshake_open(repo_root: Path, spawn_id: str, transport: str = "auto") -> dict:
+def handshake_open(repo_root: Path, spawn_id: str, transport: str = "auto",
+                   peer: str = "") -> dict:
     """Record that a handover was issued. Written by the PARENT, at the moment it prints the
     prompt — not when the child replies, because the whole point is to make an unanswered
     handshake visible."""
@@ -513,6 +514,12 @@ def handshake_open(repo_root: Path, spawn_id: str, transport: str = "auto") -> d
         "state": HANDSHAKE_STATES[0],
         "transport": chosen,
         "transport_reason": why,
+        # HOW TO ADDRESS THE CHILD. `SendMessage` takes the name `ListAgents` shows, and until
+        # 2026-09-08 this file recorded none — so the parent knew a handshake was open and had no
+        # idea who to send the chase or the verdict to. Usually EMPTY at open: the child does not
+        # exist yet. The parent fills it in from the `from-name` of the child's first message,
+        # which is the only moment either side reliably knows that name.
+        "peer": peer,
         "opened_at": int(time.time()),
         "history": [],
     }
@@ -529,7 +536,8 @@ def handshake_read(repo_root: Path, spawn_id: str) -> dict | None:
         return None
 
 
-def handshake_record(repo_root: Path, spawn_id: str, event: str) -> tuple[dict | None, str]:
+def handshake_record(repo_root: Path, spawn_id: str, event: str,
+                     peer: str = "") -> tuple[dict | None, str]:
     """Advance the handshake. Never rewinds: a verdict cannot un-answer the questions, and an
     out-of-order event is a sign the operator has lost track of which round they are in — which
     is exactly when a silent overwrite would hurt."""
@@ -541,13 +549,31 @@ def handshake_record(repo_root: Path, spawn_id: str, event: str) -> tuple[dict |
         return state, (f"already at `{state['state']}`; `{event}` would not move it forward. "
                        "Refusing rather than rewriting — an out-of-order event means the round "
                        "is not the one you think it is.")
-    state["history"].append({"event": event, "at": int(time.time())})
+    if peer:
+        state["peer"] = peer
+    state["history"].append({"event": event, "at": int(time.time()),
+                             **({"peer": peer} if peer else {})})
     state["state"] = target
     _handshake_path(repo_root, spawn_id).write_text(
         json.dumps(state, indent=2) + chr(10), encoding="utf-8")
     return state, ""
 
 
+def chase_instruction(state: dict) -> str:
+    """What to actually DO when a chase is due — addressed if we can, honest if we cannot."""
+    peer = (state.get("peer") or "").strip()
+    if state.get("transport") != "message":
+        return ("This handshake is on the paste route, so the chase goes through the human. Say "
+                "so explicitly — otherwise they watch nothing happen and conclude it is broken.")
+    if peer:
+        return f'SendMessage to: "{peer}"  — carry TWO FRESH questions, not just a reminder.'
+    return ("No peer address recorded, so the child has not made contact yet — which is itself "
+            "the signal. Run `ListAgents` and look for a session in this repo; a session started "
+            "seconds ago may be absent from one listing, so a single empty result is not proof it "
+            "does not exist. Once it replies, capture the name: "
+            "`handshake record --id <id> --event answers --peer <from-name>`.")
+
+
 def handshake_chase_due(state: dict, now: int | None = None) -> int:
     """Seconds overdue for a chase, or 0. Only meaningful while awaiting answers.
 
@@ -611,6 +637,9 @@ def main(argv: list[str] | None = None) -> int:
     h.add_argument("--repo-root", default=".")
     h.add_argument("--event", choices=sorted(_EVENT_STATE))
     h.add_argument("--transport", choices=["auto", "message", "paste"], default="auto")
+    h.add_argument("--peer", default="",
+                   help="the child's name as ListAgents shows it — take it from the `from-name` "
+                        "of its first message; that is the only moment it is reliably known")
     q = sub.add_parser("verify-question")
     q.add_argument("--answer-in", required=True)
     q.add_argument("--needle", required=True)
@@ -677,7 +706,7 @@ def main(argv: list[str] | None = None) -> int:
 
     if a.cmd == "handshake":
         if a.action == "open":
-            st = handshake_open(root, a.id, a.transport)
+            st = handshake_open(root, a.id, a.transport, a.peer)
             print(f"[spawn] handshake {a.id} open — transport `{st['transport']}` "
                   f"({st['transport_reason']})")
             if st["transport"] == "paste":
@@ -691,23 +720,29 @@ def main(argv: list[str] | None = None) -> int:
             return EXIT_REFUSED
         if a.action == "status":
             over = handshake_chase_due(st)
-            print(f"[spawn] {a.id}: {st['state']} via {st['transport']}")
+            peer = st.get("peer") or "(not recorded — see below)"
+            print(f"[spawn] {a.id}: {st['state']} via {st['transport']}, peer {peer}")
             if over:
                 print(f"  CHASE DUE — {over}s past the {CHASE_AFTER_S}s window. Silence is not "
                       "success: a child that skipped the gate and started work looks exactly "
-                      "like one still reading. Ask, and carry TWO FRESH questions, which cannot "
-                      "have been pre-read in the handover.")
+                      "like one still reading.")
+                print("  " + chase_instruction(st))
             return EXIT_OK
         if a.action == "record":
             if not a.event:
                 sys.stderr.write("[spawn] --event is required for `record`" + chr(10))
                 return EXIT_REFUSED
-            st, err = handshake_record(root, a.id, a.event)
+            st, err = handshake_record(root, a.id, a.event, a.peer)
             if err:
                 sys.stderr.write("[spawn] " + err + chr(10))
                 return EXIT_REFUSED
             print(f"[spawn] {a.id}: {st['state']}")
             return EXIT_OK
+        if a.action == "close" and not (st.get("peer") or "").strip() \
+                and st["state"] != HANDSHAKE_STATES[0]:
+            # Contact happened but nobody wrote down who with. The verdict has to reach someone.
+            print("  note  no peer recorded although the handshake progressed — re-run "
+                  "`record --peer <from-name>` so the next session can see who this was with.")
         ok, msg = handshake_close(root, a.id)
         (print if ok else sys.stderr.write)("[spawn] " + msg + ("" if ok else chr(10)))
         return EXIT_OK if ok else EXIT_REFUSED

package/bundles/antigravity-plugin/skills/cross-review/SKILL.md

@@ -64,9 +64,19 @@ fi
 > had been fixed on 2026-08-01 — the fix just never reached the caller, because a file someone
 > copied weeks earlier silently won. `caddis_gate.py vendor-drift` now fails on the same condition.
 ```
-python "$TOOL"                                           # DeepSeek eyes (default)
-python "$TOOL" --provider glm                            # GLM eyes
-python "$TOOL" --range $ARGUMENTS                        # review a git range, e.g. origin/main..HEAD
+python "$TOOL" $ARGUMENTS                                # pass the user's flags THROUGH, raw
+python "$TOOL"                                           # no arguments: DeepSeek eyes on the working tree
+```
+
+**`$ARGUMENTS` goes through raw, and must not be re-prefixed.** Callers are told to type the flag
+themselves — `feature-plan.md` emits `/caddis:cross-review --range main..HEAD` into every plan it
+writes. This line used to prefix the flag itself, which turned that into a doubled
+`--range --range main..HEAD` and made every plan-emitted call fail. Whatever the user typed is already a complete flag list:
+
+```
+/caddis:cross-review                          -> the working tree, DeepSeek
+/caddis:cross-review --range main..HEAD       -> that range
+/caddis:cross-review --provider glm           -> GLM eyes
 ```
 Optional: `--base-url <url>`, `--model <id>` (env always overrides the preset).
 

package/bundles/antigravity-plugin/skills/glossary/SKILL.md

@@ -15,7 +15,7 @@ Your job is the half a script cannot do: **write what the words mean here.**
 ## Step 1 — get the candidates
 
 ```
-python <caddis-plugin-root>/scripts/caddis_glossary.py
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_glossary.py"
 ```
 
 It ranks the words this repo says often that plain English does not, and marks which already

package/bundles/antigravity-plugin/skills/handoff/SKILL.md

@@ -26,7 +26,7 @@ is to run it.
 git status --short
 git branch --show-current
 git log --oneline -5
-python scripts/caddis_inventory.py          # what EXISTS — do not compose this from memory
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_inventory.py"          # what EXISTS — do not compose this from memory
 ```
 Then read the active plan in `.caddis/plans/` (falling back to legacy `.github/plans/` if present) and its tracker.
 
@@ -85,6 +85,21 @@ had developed by then.
 
 Record the outcome in relay.md's `## Learnings captured` line (below).
 
+## Step 2c — was any of it the harness?
+
+**One question, asked here because here is where you are already reflecting.** The observations
+that reach caddis today are the ones someone happened to recall days later — so small, frequent
+friction never arrives, which is exactly the friction worth fixing.
+
+If a command was awkward, a gate fired wrongly, a doc sent you the wrong way: park it against the
+harness, not this repo.
+
+```
+/caddis:park --harness <what was awkward, and what you expected>
+```
+
+Nothing to say is the normal answer. Say nothing and move on — this must not become a ritual.
+
 ## Step 3 — write the resume doc (overwrite) with exactly these sections
 > **Where to write:** solo / single active branch → `.caddis/relay.md` (default).
 > **Team / parallel branches** → write `.caddis/relay/<current-branch>.md` instead, so two

package/bundles/antigravity-plugin/skills/kb/SKILL.md

@@ -15,7 +15,7 @@ It ships with the harness. Try, in order:
 
 ## Step 2 — run the reindexer
 ```
-python <path>/check_doc_coverage.py --reindex
+python "${CLAUDE_PLUGIN_ROOT}/scripts/check_doc_coverage.py" --reindex
 ```
 It is **additive and safe** — never deletes your rows:
 - **Missing map** → creates `.caddis/kb/DOC-MAP.md` from a scaffold, pre-linking the repo's obvious
@@ -32,18 +32,33 @@ Read the `[kb]` summary it printed, then:
   - The note is **gone for good** → remove its row. To clear all dangling rows at once, use the
     destructive opt-in — but **show the dangling list and confirm with the user first**:
     ```
-    python <path>/check_doc_coverage.py --prune
+    python "${CLAUDE_PLUGIN_ROOT}/scripts/check_doc_coverage.py" --prune
     ```
     `--prune` removes *only* index rows that link to missing files (never valid rows, never prose),
     and still indexes any orphan notes in the same run.
 
 ## Step 4 — verify clean
 ```
-python <path>/check_doc_coverage.py --check
+python "${CLAUDE_PLUGIN_ROOT}/scripts/check_doc_coverage.py" --check
 ```
 Exit `0` = the index is honest (no dangling links; every note indexed). The SessionStart hook will now
 surface the `[DOC-MAP]` "read the index first" pointer for future sessions in this repo.
 
+## Step 5 — was any of it the harness?
+
+**One question, asked here because here is where you are already reflecting.** The observations
+that reach caddis today are the ones someone happened to recall days later — so small, frequent
+friction never arrives, which is exactly the friction worth fixing.
+
+If a command was awkward, a gate fired wrongly, a doc sent you the wrong way: park it against the
+harness, not this repo.
+
+```
+/caddis:park --harness <what was awkward, and what you expected>
+```
+
+Nothing to say is the normal answer. Say nothing and move on — this must not become a ritual.
+
 ## KB note format (OKF-lite — mandatory for every new note)
 
 Every new `.caddis/kb/*.md` note starts with this frontmatter block. **`type` is the only required

package/bundles/antigravity-plugin/skills/migrate-dir/SKILL.md

@@ -29,7 +29,7 @@ pass `--allow-dirty` on a tree whose changes you didn't make.
 
 ## Step 3 — dry run
 ```
-python <path>/caddis_migrate_dir.py <target>
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_migrate_dir.py" <target>
 ```
 Read the plan it prints. Two shapes:
 - **Simple** — only `.claudster/` exists → one `git mv .claudster .caddis` (history preserved).
@@ -42,7 +42,7 @@ Show the user the dry-run output before applying.
 
 ## Step 4 — apply
 ```
-python <path>/caddis_migrate_dir.py <target> --apply
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_migrate_dir.py" <target> --apply
 ```
 It also rewrites `.claudster/…` path references inside the repo's **live** state — `.caddis/relay.md`
 and `.caddis/workstreams.json` (parked-workstream plan paths). Historical artifacts (past plans,
@@ -53,7 +53,7 @@ Resolve any CONFLICT it reported by hand, then re-run — the command is idempot
 ## Step 5 — verify, then commit
 ```
 git -C <target> status --short          # renames should show as R (history preserved)
-python <path>/caddis_migrate_dir.py <target> --check    # exit 0 = no legacy dir left
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_migrate_dir.py" <target> --check    # exit 0 = no legacy dir left
 ```
 Then run the repo's own gate (its tests, and `check_doc_coverage.py --check` if present) and commit
 the rename **on its own**, e.g. `chore(caddis): migrate .claudster/ -> .caddis/`.

package/bundles/antigravity-plugin/skills/park/SKILL.md

@@ -20,12 +20,41 @@ The request is **$ARGUMENTS**.
 
 | `$ARGUMENTS` | Do this |
 |---|---|
+| starts with `--harness` | Go to **Harness mode** — the item is about caddis, not this repo |
 | empty or `list` | Go to **List mode** |
 | `done <slug>` or `drop <slug>` | Go to **Close mode** |
 | anything else | Go to **File mode** — the text is what to park |
 
 ---
 
+## Harness mode — `--harness`
+
+**Use it when the friction was caused by the harness, not the project.** You are almost certainly
+in an app repo right now, because that is where harness friction is noticed. Parking it here sends
+it somewhere the maintainer never reads.
+
+```bash
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_harness_path.py"
+```
+
+Prints the caddis SOURCE checkout, or **fails with exit 1 and says how to set it**. Write the item
+to `<that path>/.caddis/parking-lot/<slug>.md`, following File mode below, plus:
+
+```yaml
+scope: harness              # so a later sweep can find it mechanically
+found-by: <this repo> / session <id>
+```
+
+**On a non-zero exit, STOP and show the message.** Do not fall back to the local repo — an item
+filed there is the status quo this flag exists to end. Setting it is one command and is remembered.
+
+**Never commit it.** Capture is cheap and safe; deciding is not. Leave the file for the maintainer.
+
+Not the installed plugin: `CLAUDE_PLUGIN_ROOT` is a read-only copy replaced on every
+`claude plugin update`, so an item written there is discarded.
+
+---
+
 ## File mode
 
 ### Step 1 — check it belongs here
@@ -88,7 +117,7 @@ Rules the gate enforces — get them right the first time:
 Run the gate and show the result:
 
 ```bash
-python scripts/caddis_gate.py parking-lot --repo-root .
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_gate.py" parking-lot --repo-root .
 ```
 
 Exit 0 means it conforms. Exit 1 means fix what it printed, then re-run. Do not report the item as
@@ -109,7 +138,7 @@ Read every `.caddis/parking-lot/*.md` (skip `README.md` and `done/`). Print one
 |---|---|---|---|---|
 
 Below the table, print the counts: how many open, how many committed (`future: yes`). Then run
-`python scripts/caddis_gate.py parking-lot --repo-root .` and report any violation it prints.
+`python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_gate.py" parking-lot --repo-root .` and report any violation it prints.
 
 If the directory is empty, say so in one line. Do not invent items.
 
@@ -122,5 +151,5 @@ If the directory is empty, say so in one line. Do not invent items.
 3. **For `dropped`, append a `## Why dropped` section.** This is not optional. An item deleted with
    no reason gets re-raised by the next session that has the same idea; an item kept with "no,
    because ..." does not.
-4. Run `python scripts/caddis_tidy.py --apply`, which moves it into `.caddis/parking-lot/done/`.
+4. Run `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_tidy.py" --apply`, which moves it into `.caddis/parking-lot/done/`.
 5. Report the file's new path in one line.

package/bundles/antigravity-plugin/skills/ship/SKILL.md

@@ -44,6 +44,23 @@ git rev-parse HEAD      # record SHA for monitoring
 ```
 Use conventional commits: `fix:`, `feat:`, `chore:`, `refactor:`, `docs:`. Scope = affected module.
 
+**2b. CROSS-REVIEW TRIGGER** — `ship` has no review pause at all, which is how sixteen fixes reached production unreviewed in one day.
+
+**Run the trigger, do not eyeball the diff:**
+
+```bash
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_gate.py" review-trigger --range <base>...HEAD
+```
+
+Exit **0** — say nothing, carry on. Exit **2** — it prints which rule fired and on which files.
+Run `/caddis:cross-review`, show the findings, and let the user decide. It **never blocks**: this
+picks when to ask for a second opinion, it is not a verdict, and a review gate that blocks a ship
+gets switched off inside a week.
+
+It fires on SQL and repositories, `services/`, caches and refresh jobs, auth and RBAC, or a diff
+over 400 changed lines. No judgement in any of those — deliberately, because judgement is exactly
+what failed.
+
 **3. PUSH** — to the repo's default branch (confirm the branch first; don't assume `main`):
 ```
 git push origin <branch>

package/bundles/antigravity-plugin/skills/ship-pr/SKILL.md

@@ -50,6 +50,33 @@ are uncommitted.)
 - Without a named guard, apply the generic infra-vs-product mixed-diff heuristic as a **warning
   only** — surface it and proceed (repos without a guard allow mixed PRs by construction).
 
+## Step 3b — Cross-review trigger (before anything is pushed)
+
+**Run the trigger, do not eyeball the diff:**
+
+```bash
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_gate.py" review-trigger --range <base>...HEAD
+```
+
+Exit **0** — say nothing, carry on. Exit **2** — it prints which rule fired and on which files.
+Run `/caddis:cross-review`, show the findings, and let the user decide. It **never blocks**: this
+picks when to ask for a second opinion, it is not a verdict, and a review gate that blocks a ship
+gets switched off inside a week.
+
+It fires on SQL and repositories, `services/`, caches and refresh jobs, auth and RBAC, or a diff
+over 400 changed lines. No judgement in any of those — deliberately, because judgement is exactly
+what failed.
+
+> **Why this is mechanical and not "consider a review here".** serve-sight shipped four
+> production releases in one day — sixteen fixes across SQL, caches, refresh jobs and React — and
+> `/caddis:cross-review` ran **zero times**. Nothing was broken: the tool reported itself ready
+> with two providers keyed. Nothing decided *when* to call it. Measured there: 4 of 39 plan files
+> mention cross-review, and all four came from `/caddis:feature-plan`, which writes the line into
+> the plan template it emits. So planned feature work got reviewed and a bug batch did not —
+> **review coverage inversely correlated with urgency.** Two of that day's sixteen fixes were
+> diff-visible defects, including a cache whose docstring said "cached for the instance's life"
+> while a dependency rebuilt the object per request, so the cache was never once read.
+
 ## Step 4 — Rebase-safe currency
 
 - If the branch is **behind** the default branch, offer to rebase onto it (stale branches are how

package/bundles/antigravity-plugin/skills/spawn-session/SKILL.md

@@ -242,6 +242,20 @@ python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" handshake status --id <id
 Two questions asked at chase time cannot have been pre-read in the handover, which is a stronger
 test than the original set — and it costs nothing, since you are holding the context anyway.
 
+**Write down HOW to reach the child the moment it first messages you.** `SendMessage` addresses a
+peer by the name `ListAgents` shows, and you cannot know that name before the child exists — it
+arrives as the `from-name` on its first message. Capture it there or you will be holding an open
+handshake with no way to send the chase or the verdict:
+
+```bash
+... handshake record --id <id> --event answers --peer <from-name>
+```
+
+`handshake status` then prints the address, so a chase is a copy-paste. With no peer recorded it
+says so plainly, because **that is itself the signal**: the child has not made contact. Run
+`ListAgents` — and note a session started seconds ago can be missing from one listing, so a single
+empty result is not proof it does not exist.
+
 Record each step, and the parent may not finish until the child has acknowledged:
 
 ```bash

package/bundles/antigravity-plugin/skills/statusline/SKILL.md

@@ -39,10 +39,10 @@ Find the renderer in this install and run it. Try these paths in order and use t
 Then:
 
 ```bash
-python <path>/caddis_statusline.py --install          # both hosts
-python <path>/caddis_statusline.py --install --host claude
-python <path>/caddis_statusline.py --install --host agy
-python <path>/caddis_statusline.py --install --dry-run # print, write nothing
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_statusline.py" --install          # both hosts
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_statusline.py" --install --host claude
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_statusline.py" --install --host agy
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_statusline.py" --install --dry-run # print, write nothing
 ```
 
 `--install` does four things:

package/bundles/manifest.json

@@ -1,7 +1,7 @@
 {
-  "poolVersion": "1.3.93",
+  "poolVersion": "1.3.95",
   "bundles": {
-    "antigravity-plugin": "1.3.93",
+    "antigravity-plugin": "1.3.95",
     "antigravity-plugin-extras": "1.3.28",
     "codex": "unknown"
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caddis/cli",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "Install, update and diagnose the caddis dev harness across every coding agent you use (Claude Code, agy/Antigravity, and more).",
   "keywords": [
     "caddis",