@caddis/cli 0.3.0 → 0.4.1

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

@@ -896,6 +896,7 @@ agent-log.jsonl
 .last-usage-review
 relay.md
 relay/
+session-state.md
 PROJECT-FACTS.md
 memory.jsonl
 """
@@ -941,11 +942,14 @@ allow = [
 #                                                # accepted back-compat alias for this key.
 # ignore_routes = ["/health", "/__internal"]     # routes intentionally left out of the page guide
 
-# ── [dream_memory] — short-term fact store (scripts/dream_memory.py) ── LIVE ──
-# [dream_memory]
-# prune_age_days = 14    # single-hit facts older than this decay out
-# max_facts = 200        # hard cap on the store
-# surface_limit = 5      # how many facts SessionStart prints
+# ── [handover] — what /caddis:handoff measures (scripts/caddis_inventory.py) ── LIVE ──
+# [handover]
+# test_cmd = "pytest tests/ -q"   # THIS REPO'S test command. Without it the inventory
+#                                 # guesses `pytest` at the root, which is right in a
+#                                 # single-package repo and wrong in any repo carrying a
+#                                 # vendored or generated tree. Generated trees
+#                                 # (vscode-extensions/, dist/, node_modules/, .venv/) are
+#                                 # excluded automatically; set this when that is not enough.
 """
 
 
@@ -1128,12 +1132,13 @@ def scaffold_artifact_dir(target: Path, dry: bool) -> list[str]:
     """Create the harness-owned .caddis/ artifact tree + a default .gitignore + a config example.
 
     Committed subdirs: plans, handoffs, agent-docs, prd, kb, prompts, comms. Transient state
-    (reviews/*.html, usage-log.jsonl, .last-usage-review, relay*, PROJECT-FACTS.md, memory.jsonl)
-    is gitignored. .caddis/ is the default home for every working-artifact kind (Track A
+    (reviews/*.html, usage-log.jsonl, .last-usage-review, relay*, session-state.md,
+    PROJECT-FACTS.md, memory.jsonl) is gitignored. .caddis/ is the default home for every working-artifact kind (Track A
     Phase A3) — kb/ and prompts/ round out plans/prd/agent-docs/reviews so nothing has to
     scatter to the repo root or .github/. Also drops a documented `config.toml.example`
-    (guard/doc_coverage/dream_memory). Idempotent; never clobbers an existing .gitignore or
-    config example.
+    (guard/doc_coverage). Idempotent. An existing .caddis/.gitignore is never clobbered or
+    reordered, but MISSING entries are appended — otherwise a repo set up before an entry
+    existed would never receive it. The config example is left alone entirely.
 
     Writes into the repo's `.caddis/`.
     """
@@ -1195,7 +1200,34 @@ def scaffold_artifact_dir(target: Path, dry: bool) -> list[str]:
         notes.append(f"scaffold: wrote {label}/kb/environment-map.md")
     gi = root / ".gitignore"
     if gi.exists():
-        notes.append(f"scaffold: {label}/.gitignore present — kept")
+        # APPEND what is missing rather than keeping the file frozen. The old behaviour was
+        # "present -> kept", so a repo scaffolded before an entry was added NEVER received it.
+        # That is not hypothetical: `session-state.md` is rewritten by the Stop hook on every
+        # turn and contains the operator's verbatim words, and an already-scaffolded repo was
+        # sitting one hook-fire away from committing it.
+        #
+        # Only ever adds; a line the user wrote themselves is never touched or reordered.
+        try:
+            existing = gi.read_text(encoding="utf-8")
+        except OSError:
+            existing = ""
+        have = {ln.strip() for ln in existing.splitlines()}
+        missing = [
+            ln for ln in ARTIFACT_GITIGNORE.splitlines()
+            if ln.strip() and not ln.startswith("#") and ln.strip() not in have
+        ]
+        if not missing:
+            notes.append(f"scaffold: {label}/.gitignore present — up to date")
+        else:
+            if not dry:
+                block = "" if existing.endswith("\n") or not existing else "\n"
+                block += "\n# added by caddis — newer transient artifacts\n"
+                block += "\n".join(missing) + "\n"
+                gi.write_text(existing + block, encoding="utf-8")
+            notes.append(
+                f"scaffold: {label}/.gitignore — added {len(missing)} missing entry(ies): "
+                + ", ".join(missing)
+            )
     else:
         if not dry:
             root.mkdir(parents=True, exist_ok=True)

package/bundles/antigravity-plugin/session_end_agy.py

@@ -41,16 +41,39 @@ def _hook_note(feature, exc, root=None):
     except Exception:
         pass
 
+
+def _workspace_roots(data):
+    """Every workspace root in the payload, as a list. Empty when the payload has none.
+
+    agy sends `workspacePaths` as a LIST. All three caddis agy hooks used to read
+    `workspacePaths[0]` and treat it as "the workspace" — silently, with no signal that a
+    choice had been made. In a single-root workspace that is correct and the behaviour here
+    is unchanged. In a MULTI-root workspace it is a coin toss: the hook acts on the first
+    root regardless of which one the session is actually working in.
+
+    Nothing on this machine is multi-root today, so this has never fired. It is a live trap
+    for exactly the multi-repo workspaces the leakage investigation was about, which is why
+    each caller below now handles the list rather than assuming its first element.
+    """
+    roots = data.get("workspacePaths") if isinstance(data, dict) else None
+    if not isinstance(roots, list):
+        return []
+    return [str(r) for r in roots if isinstance(r, (str, bytes)) and str(r).strip()]
+
 def main() -> None:
     try:
         data = json.load(sys.stdin)
     except Exception:
         data = {}
     try:
-        workspaces = data.get("workspacePaths") or []
-        workspace = workspaces[0] if workspaces else os.getcwd()
-        art = _artifact_root(workspace)
-        os.makedirs(art, exist_ok=True)
+        roots = _workspace_roots(data) or [os.getcwd()]
+        # Write the record to every root that ALREADY has a .caddis dir, rather than to
+        # whichever root happened to be first. A multi-root session's usage belongs to each
+        # repo that participates in it, and creating .caddis in a repo that never opted in
+        # would be caddis littering someone else's tree.
+        targets = [_artifact_root(r) for r in roots if os.path.isdir(_artifact_root(r))]
+        if not targets:
+            targets = [_artifact_root(roots[0])]  # single-root default: unchanged behaviour
         record = {
             "ts": datetime.now(timezone.utc).isoformat(),
             "event": "session_end",
@@ -60,8 +83,10 @@ def main() -> None:
             "terminationReason": data.get("terminationReason"),
             "model": data.get("modelName"),
         }
-        with open(os.path.join(art, "usage-log.jsonl"), "a", encoding="utf-8") as fh:
-            fh.write(json.dumps(record) + "\n")
+        for art in targets:
+            os.makedirs(art, exist_ok=True)
+            with open(os.path.join(art, "usage-log.jsonl"), "a", encoding="utf-8") as fh:
+                fh.write(json.dumps(record) + "\n")
     except Exception as _exc:
         _hook_note("agy usage-log write", _exc)  # never fail the turn
     # No stdout: agy interprets a Stop hook's stdout as a decision object.

package/bundles/antigravity-plugin/skills/_registry.md

@@ -39,6 +39,7 @@
 | Ci Cd Pipeline | `ci-cd-pipeline/` | CI/CD pipeline design and implementation for GitHub Actions, Azure DevOps, and general pipeline architecture. Use when creating build pipelines, deployment workflows, quality gates, environment promotion strategies, or automating release processes. |
 | Gh Cli | `gh-cli/` | GitHub CLI operations — issues, PRs, releases, and repo management |
 | Git Commit | `git-commit/` | Create well-structured conventional commit messages following Conventional Commits standard. Use when committing changes, preparing PRs, or generating changelogs. |
+| Safe Cleanup | `safe-cleanup/` | Use BEFORE deleting any directory tree, clearing a scratchpad, removing git worktrees, or "tidying up" generated folders - especially on Windows, where a recursive delete that meets a junction or symlink destroys the link's TARGET. Also use when verifying that a Python venv or node_modules survived a cleanup, because pip check and file counts both report healthy on a half-deleted environment. |
 | Using Git Worktrees | `using-git-worktrees/` | Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification |
 | Windows Deployment | `windows-deployment/` | Deploy FastAPI + React/Vite apps to Windows Server with NSSM services, reverse proxy (IIS or nginx), and git-pull workflow. Use when deploying any web app to a Windows prod server, setting up NSSM services, configuring IIS or nginx reverse proxy, making code environment-aware for dev/prod, or troubleshooting prod deployment issues. |
 

package/bundles/antigravity-plugin/skills/advisory-hub/SKILL.md

@@ -93,6 +93,50 @@ A three-phase feature hits none of this. `/caddis:feature-plan` Step 3b runs thi
 it never creates the file silently. This is the test's only home — do not restate the thresholds
 elsewhere, or the copies drift.
 
+### Failing this test correctly does not mean "no discipline"
+
+A plan can fail the test above — properly, no Hub needed — and still be multi-phase, multi-session,
+and worth structuring. The trap is what happens next.
+
+The Hub's file conventions are *attractive*. Once one plan in a repo runs in Hub mode, its
+`phase-NN.prompt.md` / `phase-NN.report.md` / CONTINUE GATE artefacts are sitting right there as the
+most recent example of "how we structure a multi-session plan here." A second, smaller plan copies
+them by analogy. It gets the readability. It gets **none** of the safety, because the safety was
+never in the file names — it was in the role split and the verdict gate.
+
+That has happened. A six-phase UI plan borrowed the naming, and an implementing session filed its own
+batch report **and then wrote the next batch's prompt in the same session**, with nobody having
+looked at the work in between. Nothing was wrong that time. Nothing *checked*, either — and the good
+outcome is not evidence the mechanism worked, it is evidence nothing tested it.
+
+This skill already says why role separation is not decoration:
+
+> *An implementer that writes its own verdict has produced a self-assessment wearing a verdict's
+> name — worse than no verdict, because it looks like a check happened.*
+
+The same sentence holds with two words changed: **an implementer that writes the next phase's
+instructions** has produced a plan wearing an independently-authored prompt's name.
+
+### The one lightweight rule — cheap enough to always afford
+
+> **The session that files a phase's report must not also write the next phase's prompt without an
+> independent re-check in between.**
+
+That is the whole rule. It costs minutes, not a session:
+
+- re-run the test suite rather than trusting the report's claim that it passed
+- grep the source for the report's two or three load-bearing claims
+- open one or two of the screenshots it describes, rather than reading its description of them
+
+No switch file. No dedicated Hub session. No advisory-context doc. If the re-check finds nothing, you
+have lost ten minutes; if it finds something, it found it *before* the wrong instruction went into a
+fresh session that cannot know any better.
+
+**State which one you are doing, in the plan.** A plan that borrows Hub file conventions should say
+either "full Advisory Hub mode" or "Hub file conventions, lightweight re-check rule, no Hub" —
+because a reader six phases later cannot tell the two apart from the artefacts alone. That is the
+entire problem this section exists to prevent.
+
 ## Succession is not the same as a standing validator
 
 Two things look alike from outside and are not:

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

@@ -8,6 +8,17 @@ license: Apache-2.0
 
 # Code Review
 
+> **On Claude Code, prefer the native `/code-review`.** It is a command, not a skill, so it always
+> fires — including headless — and it has grown capabilities this one does not have: effort levels
+> (`low`…`max`), an `ultra` mode that runs a multi-agent review in the cloud, `--comment` to post
+> findings as inline PR comments, and `--fix` to apply them to the working tree. Reach for it first.
+>
+> This surface remains because caddis ships to harnesses that have **no** native equivalent — agy,
+> Codex and Copilot. There it is the only review you get. Do not delete it to tidy up Claude Code.
+>
+> `/caddis:cross-review` is NOT replaced by either. It sends the diff to a **different vendor's**
+> model, which neither this nor the native reviewer can do.
+
 ## Review Categories
 
 ### 1. Security Review

package/bundles/antigravity-plugin/skills/feature-plan/SKILL.md

@@ -349,6 +349,27 @@ this. But **always record the determination in the plan, pass or fail**: one lin
 > `Advisory Hub: not applicable — no REQUIRED trigger (not a migration / security change /
 > production data correctness / numbers published to stakeholders).`
 
+### If the test FAILS but this repo already runs a Hub for another plan
+
+Check for an existing `*-advisory-context.md` in `.caddis/plans/` belonging to a **different** plan.
+If one exists, add a second line under `## Constraints & decisions`:
+
+> `Hub conventions: this repo runs Advisory Hub for <other-plan>. This plan does NOT — if it borrows
+> the phase-NN.prompt.md / .report.md / CONTINUE GATE conventions, the lightweight rule applies: the
+> session that files a report must not write the next prompt without an independent re-check.`
+
+**Why this line exists.** A repo with one Hub plan has its artefacts sitting there as the most recent
+example of "how we structure a multi-session plan here", and the next plan copies them by analogy.
+It inherits the file names and none of the safety, because the safety was never in the names.
+Measured once already: an implementing session filed its own batch report and then wrote the next
+batch's prompt in the same session, with nobody having looked in between. Nothing was wrong that
+time — and nothing checked either.
+
+This is the cheapest possible place to catch it: when the second plan is created, before any
+artefact-mimicry has happened. See *"Failing this test correctly does not mean no discipline"* in the
+`advisory-hub` skill for the rule itself. Do not restate the rule here — one home, or the copies
+drift.
+
 Silent to the human, auditable in the artifact. "Say nothing" once meant *leave no trace anywhere*,
 and a wrong negative was then invisible — no line in the plan, no line in the chat, nothing for
 anyone to challenge. A rule whose failures leave no artifact cannot be reviewed.

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

@@ -5,6 +5,17 @@ description: Deterministic headless code review — adversarial diff review, sel
 
 # /caddis:gate-review — headless adversarial code review (self-contained)
 
+> **On Claude Code, prefer the native `/code-review`.** It is a command, not a skill, so it always
+> fires — including headless — and it has grown capabilities this one does not have: effort levels
+> (`low`…`max`), an `ultra` mode that runs a multi-agent review in the cloud, `--comment` to post
+> findings as inline PR comments, and `--fix` to apply them to the working tree. Reach for it first.
+>
+> This surface remains because caddis ships to harnesses that have **no** native equivalent — agy,
+> Codex and Copilot. There it is the only review you get. Do not delete it to tidy up Claude Code.
+>
+> `/caddis:cross-review` is NOT replaced by either. It sends the diff to a **different vendor's**
+> model, which neither this nor the native reviewer can do.
+
 Perform an adversarial code review of **$ARGUMENTS** (a git range, e.g. `abc123..HEAD` — defaults
 to the current working diff when empty).
 

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

@@ -137,6 +137,42 @@ This is the Hub's central power and until now it ran on human discipline alone:
 whether the next phase could start, and *nothing read it*. Five lines of check make the claim true by
 machine.
 
+### Ringing the Hub, and waiting for it (Claude Code only, optional)
+
+Two moments in Advisory-Hub mode currently cost the user a copy-paste. Both are optional, both
+degrade to today's behaviour, and neither replaces a file.
+
+**After you file `phase-NN.report.md`** — if `ListAgents` is available, look for a peer session whose
+name starts with **this repo's directory name**. Sessions are auto-named `<repo-dir>-<hash>`, so a
+same-repo peer is the Hub:
+
+```
+SendMessage({to: "<peer-name>", summary: "phase-05 report filed",
+             message: "phase-05.report.md is filed and awaiting a verdict."})
+```
+
+**When you are BLOCKED on a verdict** — instead of stopping dead, subscribe once:
+
+```
+SendMessage({to: "<peer-name>", notify_when_idle: true,
+             message: "blocked on phase-05 verdict; ping me when you have written it"})
+```
+
+`notify_when_idle` is one-shot and costs the Hub nothing extra. **Never poll `ListAgents` in a loop,
+and never send "are you done yet?"** — that burns both sessions' context to no purpose.
+
+**The rules that keep this from becoming a mess:**
+
+- **The file is the decision; the message is a doorbell.** Never treat a chat message as a verdict.
+  If a peer says "accepted", still read `phase-NN.verdict.md` — the gate above checks the FILE, and
+  a message cannot be re-read next week or by a third session.
+- **No `ListAgents`, no peer, or more than one same-repo peer → do nothing and carry on.** caddis
+  also runs on agy and Codex, which have no cross-session messaging at all. Everything above is an
+  accelerant on one harness; the file protocol is the portable layer and is what actually works.
+- **Headless runs never message.** There is no copy-paste to save.
+- **Never ask a peer to perform work your own session was denied.** Permission boundaries are
+  per-session, and routing blocked work through another session launders the user's decision.
+
 **If a `phase-NN.prompt.md` exists for the phase you are about to run, it is the INSTRUCTION OF
 RECORD** — read it, and measure your DEVIATIONS against it, not against the plan alone. The Hub writes
 that file before the phase precisely so a deviation is falsifiable; an executor that never reads it

package/bundles/antigravity-plugin/skills/safe-cleanup/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: safe-cleanup
+description: Use BEFORE deleting any directory tree, clearing a scratchpad, removing git worktrees, or "tidying up" generated folders - especially on Windows, where a recursive delete that meets a junction or symlink destroys the link's TARGET. Also use when verifying that a Python venv or node_modules survived a cleanup, because pip check and file counts both report healthy on a half-deleted environment.
+---
+
+# Safe Cleanup
+
+## Overview
+
+Cleanup looks like the safest thing you do all day. It is the most destructive.
+
+This skill exists because of a real incident: an agent created 31 directory
+junctions from throwaway worktrees into live repositories, unlinked them, saw
+"31 unlinked, 0 failed", then recursively deleted the parent. A junction it had
+never seen survived the scan, the delete followed it, and **five repositories'
+development environments were destroyed**. Every verification afterwards said
+"intact", because the verification was wrong too.
+
+Two hours of repair. None of it would have happened with the rules below.
+
+## The one-paragraph version
+
+On Windows, `Remove-Item -Recurse` **follows junctions and deletes their
+targets**. Enumerating with `-ErrorAction SilentlyContinue` hides the ones you
+cannot read. And after the damage, `pip check`, `pip list` and file counts all
+report success, because metadata survives while package files do not. So: never
+link into somewhere real, never recurse through a link, prefer rename over
+delete, and verify by *using* the thing rather than counting it.
+
+---
+
+## RULE 1 - Prefer rename over delete
+
+Rename is atomic. Recursive delete is not: it can fail half way and leave a
+directory that looks present and is unusable.
+
+```powershell
+Rename-Item -Path $target -NewName ".broken-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
+```
+
+In the incident, a venv holding `_greenlet.cp314-win_amd64.pyd` open **refused to
+delete** but **renamed fine**. Had the delete been retried or forced, it would
+have half-emptied the directory.
+
+Rename first, build fresh alongside, delete the old copy later when nothing holds
+it. Disk is cheap. An environment nobody can recover is not.
+
+## RULE 2 - Never recurse a delete through a reparse point
+
+Junctions and symlinks are transparent to `Remove-Item -Recurse`. Deleting a
+folder that contains a link to `C:\live\thing` deletes **the contents of
+`C:\live\thing`**.
+
+Check first, and **fail if the check itself cannot complete**:
+
+```powershell
+$links = @(Get-ChildItem $path -Recurse -Force -Directory -ErrorAction Stop |
+           Where-Object { $_.Attributes -band [IO.FileAttributes]::ReparsePoint })
+if ($links.Count) {
+    $links | ForEach-Object { Write-Host "  $($_.FullName) -> $($_.Target)" }
+    throw "refusing: $($links.Count) link(s) inside $path"
+}
+```
+
+`-ErrorAction SilentlyContinue` on that scan is precisely what caused the
+incident. A link inside a directory the scanner could not read was skipped in
+silence and never appeared in the count. **A scan that cannot see everything must
+fail, not shrug.**
+
+To remove a link itself, unlink it - never delete through it:
+
+```powershell
+[System.IO.Directory]::Delete($linkPath, $false)   # link only, never the target
+cmd /c rmdir "$linkPath"                            # same effect
+```
+
+## RULE 3 - Do not create links into live directories
+
+The safest delete is the one with nothing to follow.
+
+If a throwaway workspace needs dependencies, **build them there**, or point the
+tool at an absolute interpreter path. Do not junction `<scratch>\.venv` to
+`<live-repo>\.venv` for convenience - that is a loaded gun aimed at the repo, and
+any cleanup above the link can fire it.
+
+If you must link, remove the link the moment you are done, and never leave one
+inside a directory that something else will clean up.
+
+## RULE 4 - Verify by using, not by counting
+
+After any cleanup near an environment, prove it still works. These all LIE on a
+half-deleted Python venv, because dist-info metadata survives while package files
+are removed:
+
+| Check | Why it lies |
+|---|---|
+| `Test-Path .venv\Scripts\python.exe` | Proves the interpreter exists. Says nothing about packages. |
+| file or directory counts | Metadata directories inflate the count. |
+| `pip list` | Reads metadata. |
+| `pip check` | Reads metadata. Reported "No broken requirements found" on a venv that could not import fastapi. |
+| `pip install -e .` | Reads metadata, calls the package satisfied, **skips it, and reports success**. |
+
+The honest check is whether the interpreter can import what the project declares:
+
+```python
+import importlib.util
+importlib.util.find_spec("fastapi") is None   # -> True means genuinely missing
+```
+
+For node, check that a real entry point resolves, not that `node_modules` exists.
+
+**Map distribution names to import names.** `pyjwt` imports as `jwt`,
+`python-ulid` as `ulid`, `python-dotenv` as `dotenv`. A naive audit produces false
+positives and will have you rebuilding healthy environments - which is its own way
+of causing an outage.
+
+## RULE 5 - Stop what holds the files, or refuse
+
+A running service turns a delete into a **partial** delete - the worst outcome.
+
+Stop named services first. Then check for surviving processes and **refuse rather
+than force**:
+
+```powershell
+$held = @(Get-CimInstance Win32_Process -Filter "Name='python.exe'" |
+          Where-Object { $_.ExecutablePath -like "$venv\*" })
+if ($held.Count) { throw "refusing: still held by PID $($held[0].ProcessId)" }
+```
+
+In the incident's repair, this refused on one repo because a **VS Code language
+server** had held that venv since the previous day. Not a service, not safe to
+kill, not the script's business. That repo was fixed a different way. **Refusing
+was correct.**
+
+## RULE 6 - One agent at a time on a shared resource
+
+Two agents installing into the same environment concurrently can produce exactly
+this partial state. Three sessions were live in one repository during the
+incident. Whoever is repairing says so; everyone else keeps out.
+
+## RULE 7 - Verify against the source of truth, not the working copy
+
+Checkouts go stale. During the same incident a subagent reported a file as absent
+from a configuration, contradicting a change made hours earlier. The file was
+present on `origin/main`; the working copy was **10 commits behind**.
+
+Before asserting something is missing, check `git show origin/main:<path>`, not
+the file on disk.
+
+---
+
+## Before you delete anything - the checklist
+
+1. Can I **rename** instead? Do that.
+2. Does the tree contain **reparse points**? Scan with `-ErrorAction Stop`. Refuse if any, or if the scan fails.
+3. Does anything **hold files open**? Stop services; refuse on surviving processes.
+4. Did I create any **links into live directories** earlier in this session? Unlink them explicitly, by name.
+5. After: **verify by using**, not by counting.
+6. If something looks wrong: check `origin/main`, not the working copy.
+
+## What good verification output looks like
+
+Not this:
+
+```
+.venv intact: True          <- only proves python.exe exists
+31 unlinked, 0 failed       <- says nothing about what the scan missed
+No broken requirements found <- reads metadata, not reality
+```
+
+This:
+
+```
+service-a      OK   declared=24  missing=0     <- every declared dep imported
+service-b      OK   declared=19  missing=0
+```
+
+## Reference implementation
+
+The estate this skill came from keeps working tools at `.caddis/tools/`:
+
+- `venv-audit.py` - imports every dependency each `pyproject.toml` declares
+- `rebuild-venv.ps1` - renames aside, rebuilds, restarts services, refuses on links or live processes
+- `README-venv-safety.md` - the incident record
+
+Adapt rather than copy: the rules matter more than the scripts.

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

@@ -6,6 +6,15 @@ description: "Security review workflow — OWASP, code scanning, cloud infrastru
 
 # Security Review
 
+> **On Claude Code, prefer the native `/security-review`.** It is a command, not a skill, so it always
+> fires — including headless — and it has grown capabilities this one does not have: Reach for it first.
+>
+> This surface remains because caddis ships to harnesses that have **no** native equivalent — agy,
+> Codex and Copilot. There it is the only review you get. Do not delete it to tidy up Claude Code.
+>
+> `/caddis:cross-review` is NOT replaced by either. It sends the diff to a **different vendor's**
+> model, which neither this nor the native reviewer can do.
+
 Security review workflow covering OWASP Top 10, code scanning, and cloud infrastructure.
 
 ## When to Use

package/bundles/antigravity-plugin/skills/validate-phase/SKILL.md

@@ -98,6 +98,37 @@ step, not just described.
 Add or update this phase's row in `.caddis/advisory-hub-reports/README.md` (Phase | Report | Verdict |
 Outcome | Date).
 
+## Step 8 — tell the implementing session (Claude Code only, optional)
+
+The verdict file is the decision. This step only saves the user from carrying it by hand.
+
+If `ListAgents` is available, look for a peer session whose name starts with **this repo's directory
+name** — sessions are auto-named `<repo-dir>-<hash>`, so in a repo directory called `acme-api`,
+`acme-api-91` is a session in this repo and `other-project-e8` is not. If exactly one such peer
+exists, it is the implementer:
+
+```
+SendMessage({to: "<peer-name>", summary: "phase-05 verdict",
+             message: "phase-05.verdict.md written — verdict: accept-with-correction. "
+                      "Corrections are in the file and in advisory-context.md."})
+```
+
+Send the **headline and the filename**, never the whole verdict. The file is the record; the message
+is a doorbell. A chat message cannot be re-read next week; `phase-05.verdict.md` can.
+
+**Do not do any of this if:**
+
+- there is no `ListAgents` — caddis also runs on agy and Codex, which have no cross-session
+  messaging. The file-based flow is the portable one and works everywhere. This step is an
+  accelerant, not a requirement.
+- **more than one** same-repo peer is listed. Guessing which is the implementer is worse than not
+  sending — say so to the user and let them name it.
+- you are headless. There is no one to save a copy-paste for.
+
+**Never ask the peer to run something your own session was denied.** Permission boundaries are
+per-session; routing blocked work through another session launders the user's decision. Route it back
+to the user instead.
+
 ## Rules
 
 - **Fail closed.** A gate you could not re-run is `NOT RE-RUN`, never `PASS`. A claim you could not