@caddis/cli 0.4.7 → 0.4.9

package/bundles/antigravity-plugin/agents/preflight.md

@@ -6,7 +6,7 @@ description: Use this agent to validate an implementation plan (or a phase of it
 You are a plan-validation specialist. Your job: catch the plan's wrong assumptions **before** they
 become wasted implementation. You diagnose; you do not fix and you do not write code.
 
-## What to validate (7 categories)
+## What to validate (8 categories)
 For the plan (or the named phase) check each claim against the codebase:
 1. **File paths** — every file the plan says to create/edit: does the parent dir exist? Does an
    existing file already cover it (collision/duplication)?

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.94",
+  "version": "1.3.96",
   "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_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

@@ -470,8 +470,17 @@ def capture_order(repo_root: Path, spawn_id: str) -> tuple[list[str], list[str]]
 CHASE_AFTER_S = 1800
 
 # Ordered. Each event may only move the handshake forward.
-HANDSHAKE_STATES = ("awaiting-answers", "answered", "verdict-sent", "acknowledged")
-_EVENT_STATE = {"answers": "answered", "verdict": "verdict-sent", "ack": "acknowledged"}
+# Ordered. An event may only move the handshake FORWARD along this list.
+#
+# Two entry points, one list. PARENT-FIRST (the product owner starts the child, then names it)
+# begins at `awaiting-readback`, because the parent speaks first and must not take the answers on
+# trust. CHILD-FIRST (008's original: print a prompt, a human pastes it) begins at
+# `awaiting-answers`, because there the child's first message is itself the evidence of reading
+# and a read-back would be asking for something already proven.
+HANDSHAKE_STATES = ("awaiting-readback", "awaiting-answers", "answered", "verdict-sent",
+                    "acknowledged")
+_EVENT_STATE = {"readback": "awaiting-answers", "answers": "answered",
+                "verdict": "verdict-sent", "ack": "acknowledged"}
 
 
 def detect_transport(env: dict | None = None) -> tuple[str, str]:
@@ -501,7 +510,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."""
@@ -510,9 +520,16 @@ def handshake_open(repo_root: Path, spawn_id: str, transport: str = "auto") -> d
         chosen, why = transport, "forced with --transport"
     state = {
         "id": spawn_id,
-        "state": HANDSHAKE_STATES[0],
+        # Parent-first only when we can actually reach the child: a name AND a transport.
+        "state": HANDSHAKE_STATES[0] if (peer and chosen == "message") else HANDSHAKE_STATES[1],
         "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 +546,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."""
@@ -537,17 +555,48 @@ def handshake_record(repo_root: Path, spawn_id: str, event: str) -> tuple[dict |
     if state is None:
         return None, f"no handshake for {spawn_id} — run `handshake open --id {spawn_id}` first"
     target = _EVENT_STATE[event]
-    if HANDSHAKE_STATES.index(target) <= HANDSHAKE_STATES.index(state["state"]):
-        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())})
+    here = HANDSHAKE_STATES.index(state["state"])
+    there = HANDSHAKE_STATES.index(target)
+    # EXACTLY one step. Monotonic-only let `answers` jump straight over `awaiting-readback`,
+    # which silently skipped the read-back gate — the one thing the parent-first flow adds.
+    # Backwards is an operator who has lost track of the round; forwards-by-two is a gate not run.
+    if there != here + 1:
+        expected = HANDSHAKE_STATES[here + 1] if here + 1 < len(HANDSHAKE_STATES) else "nothing"
+        wanted = next((e for e, st in _EVENT_STATE.items() if st == expected), "—")
+        return state, (f"at `{state['state']}`, so the only event that fits is `{wanted}` "
+                       f"(-> `{expected}`). `{event}` would "
+                       + ("skip a step" if there > here + 1 else "move backwards")
+                       + " — refusing rather than rewriting, because a skipped step here is a "
+                         "gate that never ran.")
+    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("state") == HANDSHAKE_STATES[0] and peer:
+        return (f'No read-back from "{peer}". It was messaged and has not said what it READ, which '
+                "is the cheapest signal that it skipped the gate and started working. Ask again, "
+                "and ask for file paths — a summary can be written without opening anything.")
+    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.
 
@@ -555,7 +604,7 @@ def handshake_chase_due(state: dict, now: int | None = None) -> int:
     pre-read in the handover file — a stronger test than the original set, and free, because the
     parent is holding the context anyway.
     """
-    if state.get("state") != HANDSHAKE_STATES[0]:
+    if state.get("state") not in (HANDSHAKE_STATES[0], HANDSHAKE_STATES[1]):
         return 0
     now = int(time.time()) if now is None else now
     return max(0, now - int(state.get("opened_at", now)) - CHASE_AFTER_S)
@@ -611,6 +660,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,9 +729,17 @@ 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']})")
+                  f"({st['transport_reason']}), state `{st['state']}`")
+            if st["state"] == HANDSHAKE_STATES[0]:
+                print(f"  PARENT-FIRST. You have the address, so message \"{st['peer']}\" now: "
+                      "tell it what to read, then ask it to reply with WHICH FILES it opened "
+                      "before it answers anything. Record that with `--event readback`.")
+            elif st["transport"] == "message" and not st["peer"]:
+                print("  No --peer given, so this is the child-first flow: print the prompt and "
+                      "wait. If you already started the child, re-open with `--peer <its "
+                      "ListAgents name>` to message it directly instead.")
             if st["transport"] == "paste":
                 print("  The child cannot message you. Print the prompt for the human to carry, "
                       "and say so — otherwise they watch nothing happen and conclude it is "
@@ -691,23 +751,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/feature-plan/SKILL.md

@@ -22,6 +22,13 @@ description**, and there may be **no codebase, PROJECT-FACTS, or prior PRD** to
 write a complete best-effort plan anyway.
 
 Absolute rules in this mode (they override everything below):
+
+> **The same policy exists in `/caddis:prd`, and the two are deliberately NOT identical.**
+> Each is specialised to the artefact its command writes — where the output goes, and
+> where an unresolved decision is recorded. **Do not merge them, and do not replace
+> either with a pointer:** headless mode is precisely when no human is present and the
+> session will not go and read another command to find its own rules.
+
 - **NEVER ask a question, request clarification, or end your turn with questions.** Replying with a list
   of scoping questions is a hard failure. Never use AskUserQuestion, never pause, never wait for input.
 - **A bare title (or PRD path) is sufficient input.** Where information is missing, invent a reasonable,
@@ -112,7 +119,7 @@ escalation, never a planned default.
 
 ### Assign an execution LANE per phase (which harness runs it — not just which model)
 A tier can be served by an OSS provider instead of Anthropic (cheat sheet:
-`docs/guide/multi-model-workflow.md`; wiring: the caddis repo's `.caddis/plans/model-access.md`):
+`docs/guide/multi-model-workflow.md` (in the caddis **source** repo — `docs/` is not shipped inside the installed plugin); wiring: the caddis repo's `.caddis/plans/model-access.md`):
 - **claude** (default) — this session, `/model <alias>` as above. Required for judgment-heavy,
   security-sensitive, or novel-architecture phases.
 - **glm-headless** — mechanical, fully-specced phases run on GLM without touching Claude quota:

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,23 @@ had developed by then.
 
 Record the outcome in relay.md's `## Learnings captured` line (below).
 
+## Step 2c — was any of it the harness?
+
+<!-- shared:harness-friction-question — keep byte-identical across commands; a test pins it -->
+**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.
+<!-- /shared:harness-friction-question -->
+
 ## 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,35 @@ 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?
+
+<!-- shared:harness-friction-question — keep byte-identical across commands; a test pins it -->
+**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.
+<!-- /shared:harness-friction-question -->
+
 ## 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
@@ -68,7 +85,7 @@ generated: { by: caddis/<model-id>, at: 2026-07-28T09:00:00Z }
 
 The full schema, the caddis↔OKF `status` mapping, and what caddis deliberately skips from OKF v0.2
 (`sources:`, `Attested Computation`) live in
-[`.github/instructions/document-frontmatter.instructions.md`](../../.github/instructions/document-frontmatter.instructions.md).
+`.github/instructions/document-frontmatter.instructions.md` in the caddis source repo. (Not a link: a relative path out of the plugin directory resolves nowhere once installed.)
 
 **Backward compatible:** an existing note with no trust fields is still correct. Do not bulk-migrate
 old notes — add the fields as notes are next touched.

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/prd/SKILL.md

@@ -30,6 +30,13 @@ forbidden**. This mode exists for one-line ideas: the card may be nothing more t
 fully actionable — a terse title is enough to write a complete draft PRD.
 
 Absolute rules in this mode (they override everything above):
+
+> **The same policy exists in `/caddis:feature-plan`, and the two are deliberately NOT identical.**
+> Each is specialised to the artefact its command writes — where the output goes, and
+> where an unresolved decision is recorded. **Do not merge them, and do not replace
+> either with a pointer:** headless mode is precisely when no human is present and the
+> session will not go and read another command to find its own rules.
+
 - **NEVER ask a question. NEVER request clarification. NEVER end your turn with questions.** Replying with
   something like *"a few questions to scope this before I write the PRD"* is a hard failure. Never use
   AskUserQuestion, never pause for approval, never wait for input.

package/bundles/antigravity-plugin/skills/setup-project-ai/SKILL.md

@@ -35,7 +35,7 @@ alias claude-glm="<path-to>/claude-harness/scripts/claude-oss.sh"
 ```
 Resolve `<path-to>` per the same plugin-vs-source rule as the generator itself (`${CLAUDE_PLUGIN_ROOT}`
 for a plugin install, the harness checkout path for caddis). Also set `CADDIS_KEYS_FILE`
-(default `~/.caddis/keys.env`) with the provider keys — see `docs/guide/providers-and-keys.md`.
+(default `~/.caddis/keys.env`) with the provider keys — see `docs/guide/providers-and-keys.md` (in the caddis **source** repo — `docs/` is not shipped inside the installed plugin).
 
 ## After the deterministic step — deploy private harness skills (optional)
 

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

@@ -46,6 +46,7 @@ Use conventional commits: `fix:`, `feat:`, `chore:`, `refactor:`, `docs:`. Scope
 
 **2b. CROSS-REVIEW TRIGGER** — `ship` has no review pause at all, which is how sixteen fixes reached production unreviewed in one day.
 
+<!-- shared:cross-review-trigger — keep byte-identical across commands; a test pins it -->
 **Run the trigger, do not eyeball the diff:**
 
 ```bash
@@ -60,6 +61,7 @@ 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.
+<!-- /shared:cross-review-trigger -->
 
 **3. PUSH** — to the repo's default branch (confirm the branch first; don't assume `main`):
 ```

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

@@ -52,6 +52,7 @@ are uncommitted.)
 
 ## Step 3b — Cross-review trigger (before anything is pushed)
 
+<!-- shared:cross-review-trigger — keep byte-identical across commands; a test pins it -->
 **Run the trigger, do not eyeball the diff:**
 
 ```bash
@@ -66,6 +67,7 @@ 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.
+<!-- /shared:cross-review-trigger -->
 
 > **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

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

@@ -24,6 +24,36 @@ A long session does not forget. **It recalls superseded facts fluently.** Measur
 Each was stated with conviction and was wrong. Asking that agent what it knows cannot find any of
 it.
 
+## Start the successor FIRST, then name it
+
+**Preferred flow.** Start the child with a name you choose, then pass that same name here:
+
+```
+claude --name successor-9c2                                   # in a new terminal
+/caddis:spawn-session successor-9c2 finish the harvester      # here
+```
+
+`claude -n/--name` sets the session's display name, and that is exactly the name `SendMessage`
+addresses. You pick it, so nothing has to be looked up.
+
+**Check the row before you trust the name.** Run `ListAgents` once and confirm the child is there
+and reads `interactive`, not `offline` — a listing carries long-dead sessions, so presence alone
+proves nothing. Names are also **not unique**: if two rows share one, `SendMessage` needs the
+` [ref]` shown beside it. Pick a short distinct name and this never arises.
+
+**Why this ordering.** With the child already running you hold its address from the start, so the
+parent messages it directly and nothing has to be pasted. The older flow printed a prompt for a
+human to carry, which meant the child did not exist yet and its address could not be known.
+
+**What you give up, and how it is replaced.** In the older flow the child spoke first, so its
+first message was itself proof it had read the handover. Here the parent speaks first, so that
+proof is a separate step: **your opening message asks the child to reply with WHICH FILES it
+opened, before it answers anything.** Ask for paths — a summary can be written without opening
+anything. Record it with `--event readback`; until you do, the handshake refuses `--event answers`.
+
+**No name given?** The command falls back to the older printed-prompt flow. That is also the only
+route on agy and Codex, which have no `SendMessage`.
+
 The successor is what to pick up first: **$ARGUMENTS** (if empty, derive it from the parking-lot
 and the active plan).
 
@@ -242,6 +272,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/antigravity-plugin/skills/usage-review/SKILL.md

@@ -20,9 +20,11 @@ python "<resolved-path>" [--days $ARGUMENTS]
 ```
 
 - Default window is **7 days**. If the user passed a number (e.g. `/usage-review 14`), use it.
-- Run from the project root so `.claude/usage-log.jsonl` is found correctly.
+- Run from the project root so `.caddis/usage-log.jsonl` is found correctly. (The legacy
+  the legacy `.claude/usage-log.jsonl` is still read as a fallback during the migration.)
 - If the script exits with "No sessions found", tell the user and stop — no further steps.
-- The script prints a markdown report to stdout and writes `.claude/usage-review.html`.
+- The script prints a markdown report to stdout and writes
+  `.caddis/reviews/usage-review.html` (override with `--output-dir`).
 
 ## Step 2 — present the report
 
@@ -50,21 +52,22 @@ the two `---` delimiters) of the named agent file and change its value. Show a d
 After any applies, tell the user which files changed and suggest:
 "Run `/usage-review` again after a few sessions to see the effect."
 
-## Step 5 — offer to schedule a recurring review (optional)
+## Step 5 — do NOT offer to schedule this as a cloud routine
 
-After reporting the outcome, ask once:
+**This command cannot run as a cloud routine, and offering one produces a routine that fails.**
 
-> "Want me to schedule this to run automatically every Wednesday? I can set it up with `/schedule`."
+`/schedule` creates a **cloud** agent. This command reads `.caddis/usage-log.jsonl`, which the
+local `Stop` hook writes on THIS machine and which is **gitignored** — so it is neither on the
+cloud runner's filesystem nor in the clone it makes. The routine would fire on time and find
+nothing.
 
-If the user says yes, use the `schedule` skill to create a weekly routine:
+That also settles a contradiction this file used to carry: the description says "Data stays
+on-machine — no telemetry, no server", and the old Step 5 offered a cloud routine two screens
+later. The description is the correct half.
 
-```
-Schedule a recurring cloud routine: every Wednesday, run /usage-review
-```
-
-The routine should fire mid-week so findings are fresh for the next work sprint. If the user
-declines, skip silently — the SessionStart nudge in `inject_relay.py` already covers the
-"you haven't reviewed in 7 days" case.
+**The recurring nudge already exists and is local.** Each run updates
+`.caddis/.last-usage-review`, and the SessionStart hook reads it to remind you when a review is
+overdue. Nothing to schedule.
 
 ## Notes
 

package/bundles/antigravity-plugin/skills/use-model/SKILL.md

@@ -7,7 +7,7 @@ description: Explain (or apply) the model lanes — claude / claude-glm / cross-
 
 Explain the model-switching lanes so the user (or you, on their behalf) can move a session onto an
 OSS provider (GLM, DeepSeek, OpenRouter, or a custom endpoint) in one command, with no hardcoded key
-path. Full detail lives in the **Providers & keys** guide (`docs/guide/providers-and-keys.md`) — this
+path. Full detail lives in the **Providers & keys** guide (`docs/guide/providers-and-keys.md` (in the caddis **source** repo — `docs/` is not shipped inside the installed plugin)) — this
 command is the quick-reference + do-it-now version.
 
 ## The lanes

package/bundles/manifest.json

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

package/package.json

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