@caddis/cli 0.4.4 → 0.4.6

package/bundles/antigravity-plugin/CADDIS-GLOSSARY.md

@@ -0,0 +1,150 @@
+# Pipeline Glossary
+
+> **Shipped as `CADDIS-GLOSSARY.md`.** This defines CADDIS's own vocabulary — the words the
+> toolchain coined, which a user meets constantly and cannot guess from the plain word. Your
+> project's own terms belong in `.caddis/kb/GLOSSARY.md` instead; run `/caddis:glossary` to
+> build one. Two files, two subjects, deliberately different names.
+
+Canonical terms used across all agents, skills, and pipeline infrastructure.
+When writing agent instructions, skills, or documentation, use ONLY these terms.
+
+Two vocabularies live here and they are NOT interchangeable. **Core Terms** onward describe the
+agent PIPELINE (orchestrator, stages, `pipeline-state.json`). **Toolchain Terms** describe caddis
+as a distributed product (pool, mirror, export target). A word can be canonical in one and absent
+from the other; where they genuinely collide, the collision is named under Flagged ambiguities
+rather than resolved by fiat.
+
+Admission test, borrowed from `last30days-skill`'s CONCEPTS.md: a term belongs here when its
+project meaning is **distinct enough from its ordinary technical sense that a newcomer would
+misread it**. `commit` does not belong. `pool` does.
+
+---
+
+## Core Terms
+
+| Canonical Term | Definition | DO NOT USE |
+|---------------|------------|------------|
+| artefact | Any file produced by an agent as pipeline output. This is the correct spelling in all contexts — field names, prose, section headers. | artifact, deliverable, output file |
+| stage | A pipeline-level progression step (intent, prd, architect, plan, implement, tester, review, closed) | phase (for pipeline steps), step |
+| phase | A subdivision of work within a Plan (Phase 1, Phase 2…). Phases exist WITHIN the implement stage. | stage (for plan subdivisions), step |
+| chain_id | Feature tracking ID format: `FEAT-YYYY-MMDD-slug`. Links all artefacts for a feature. | feature_id, tracking_id |
+| handoff | Transfer of work from one agent to another via Orchestrator | routing (for the transfer act), delegation, dispatch, hand-off |
+| handoff payload | The `_notes.handoff_payload` object written by Orchestrator via `update_notes` MCP tool before routing to a specialist | routing context, task context |
+| evidence bundle | Anchor's structured proof-of-work document (`agent-docs/anchor-evidence-*.md`) | proof, verification report |
+| gate | A supervision checkpoint requiring approval before pipeline advances (`supervision_gates.*`) | checkpoint, approval point |
+| HARD STOP | Absolute refusal to proceed — security violation, out-of-scope request, or rogue state edit | halt, block, refuse |
+| skill | A reusable knowledge pack in `.github/skills/{category}/{name}/SKILL.md` | SKILL (when referring to the concept, not the filename) |
+| prompt | A reusable prompt file in `.github/prompts/*.prompt.md` | skill (when referring to prompt files — prompts are not skills) |
+| onboarding prompt | The project bootstrap prompt at `.github/prompts/onboarding.prompt.md` | onboarding skill |
+
+## Pipeline Modes
+
+| Term | Definition |
+|------|------------|
+| supervised | All gates require manual user approval. Default mode. |
+| assisted | Manual gates with AI guidance hints. Auto-routing between stages. |
+| autopilot | All gates auto-satisfied except `intent_approved`. Fully hands-free after intent approval. |
+
+## Result Statuses
+
+### MCP `notify_orchestrator` — `result_status` parameter
+
+| Value | Meaning | Used By |
+|-------|---------|---------|
+| `complete` | Standard stage completion | All agents |
+| `phase_complete` | Multi-phase loop — implement stays in implement for next phase | Implement agent |
+| `recovered` | Recovery after guard failure | Orchestrator (debug flow) |
+
+### Agent-Specific Result Fields
+
+| Agent | Field | Possible Values | Meaning |
+|-------|-------|-----------------|---------|
+| Tester | `tester_result.status` | `passed`, `failed` | All tests pass / any test fails |
+| Code Reviewer | `Verdict` | `approved`, `revision-requested` | Code meets standards / needs changes |
+| All agents (artefact YAML header) | `approval` | `approved`, `pending`, `revision-requested` | Artefact acceptance status |
+
+### Orchestrator Artefact Validation Guards
+
+| Guard | Checks |
+|-------|--------|
+| `artefact_exists` | File at `artefact_path` exists on disk |
+| `artefact_approved` | YAML header `approval:` field is `approved` |
+| `all_phases_done` | All implementation phases complete |
+
+## File Naming Conventions
+
+| Pattern | Example | Usage |
+|---------|---------|-------|
+| Agent file | `frontend-developer.agent.md` | Lowercase kebab-case matching `name` frontmatter field |
+| Skill file | `.github/skills/{category}/{name}/SKILL.md` | Category folder + name folder + SKILL.md |
+| Plan file | `.github/plans/{feature-slug}.md` | Feature slug from chain_id |
+| Evidence file | `agent-docs/anchor-evidence-{feature}.md` | Per-feature evidence bundle |
+| Artefact registry | `agent-docs/ARTIFACTS.md` | Single registry for all pipeline artefacts |
+| Pipeline state | `.github/pipeline-state.json` | Live pipeline state — written ONLY by MCP tools |
+
+## Pipeline State Field Ownership
+
+All writes to `pipeline-state.json` go through MCP tools. Only `stages[*].status`, `stages[*].artefact`, `stages[*].completed_at`, and `blocked_by` may be set via `editFiles`.
+
+| Field | Writer | Tool |
+|-------|--------|------|
+| `current_stage` | Pipeline runner | `notify_orchestrator` |
+| `supervision_gates[*]` | Orchestrator | `satisfy_gate` |
+| `pipeline_mode` | Orchestrator | `set_pipeline_mode` |
+| `_notes.*` | Orchestrator / agents | `update_notes` |
+| `project`, `feature`, `type` | Orchestrator | `pipeline_init` / `pipeline_reset` |
+
+## Common Conflations to Avoid
+
+| Wrong | Correct | Why |
+|-------|---------|-----|
+| "Phase 3 of the pipeline" | "The implement stage" | Phases are within a Plan; stages are pipeline-level |
+| "The artifact registry" | "The artefact registry" | British spelling is canonical (matches all field names) |
+| "Run the onboarding skill" | "Run the onboarding prompt" | `.prompt.md` files are prompts, not skills |
+| "Route to the agent" | "Hand off to the agent" | Routing is Orchestrator's internal logic; handoff is the transfer act |
+| `[Stage/Phase N]` | `[Phase N]` (within Plan) or `[Stage: implement]` (pipeline-level) | Don't conflate the two with a slash |
+
+---
+
+## Toolchain Terms
+
+caddis-the-product, as opposed to the agent pipeline above. These are the words caddis invented
+out of ordinary English, which is exactly why they need defining: a reader who guesses from the
+plain word gets them wrong. Usage counts were measured across 444 markdown files on 2026-08-29.
+
+| Canonical Term | Definition | DO NOT USE |
+|---|---|---|
+| pool | The single source of every shipped resource, living in `.github/` (skills, agents, commands, prompts). Everything a user installs is EXPORTED from the pool; nothing is authored in a bundle. Versioned independently of the CLI, and bumped only by `caddis-push` — never by hand. *(222 uses)* | bundle (for the source), library |
+| bundle | One EXPORTED copy of the pool, shaped for a single target — `dist/runtime-resources/<target>/`. A bundle is generated output; editing one is always a mistake. | pool (for a built copy) |
+| export target | A named consumer in `.github/runtime-targets.json` — claude, antigravity, antigravity-plugin, codex, copilot, plus `-extras` variants. Each takes a different subset and layout from the same pool. | platform, host (for a target) |
+| mirror | The public repo `saajunaid/caddis-plugin`, refreshed by `caddis-push`. The SOURCE repo is private, so the mirror is what any other machine can actually reach. | upstream, remote |
+| relay | `.caddis/relay.md` — the durable resume doc, rewritten by `/caddis:handoff` and injected at SessionStart. Machine-local and gitignored. Only changes when someone runs a handoff, so it is stale between them by design. *(168 uses)* | handoff doc, session notes |
+| session state | `.caddis/session-state.md` — auto-captured by the `Stop` hook at the end of EVERY turn. Distinct from the relay: current without anyone deciding to make it current, and it holds no agreed next step. | relay (they are different files with different guarantees) |
+| drift | A gap between what a consumer HAS installed and what the pool currently ships. `caddis status` reports it per agent. Not code drift, not schema drift. *(160 uses)* | staleness, lag |
+| live-fire | Driving a real binary end to end rather than asserting against a manifest. Coined because three defects in one month passed every test and still gave a human a broken install: the tests asked "does the export match the manifest", never "would this work". An export target is not trusted until it has been live-fired once. | smoke test, integration test, manual test |
+| parking-lot | `.caddis/parking-lot/` — the ONE register of future work. It exists because future work previously scattered to nine places and no session could answer "what is left". Items carry `severity` and `status`; the backlog IS the plan when no plan is active. *(41 uses)* | backlog file, TODO list, icebox |
+| model lane | A named provider route reached by its own binary — `claude-oss`, `claude-glm`, `claude-deepseek` — all speaking the Anthropic protocol. A lane is a route, not a model. | provider, backend, endpoint |
+| core / extras | The two shipping tiers. Core is an EXPLICIT allowlist in `.github/runtime-targets.json`; anything not named there lands in extras. A skill defaults to extras, so placement is a decision, never an accident. | tier 1 / tier 2, full / lite |
+| harness | The agent runtime that loads caddis — Claude Code, agy, Codex, Copilot. caddis is agent-agnostic; "the harness" without a name means whichever one is running. *(135 uses)* | client, IDE, platform |
+
+## Flagged ambiguities
+
+Named rather than resolved. Pretending the vocabulary is clean is how a glossary starts lying.
+
+- **`gate` is overloaded, badly.** Core Terms defines it as a supervision checkpoint requiring
+  approval. That is one of at least twelve senses in live use: *exit gate* (20), *quality gate*
+  (9), *evidence gate* (5), *decision gate* (3), plus pre-publish, handover and privacy gates —
+  none of which involve pipeline supervision. The word appears 1019 times across 168 files.
+  **Prefer the full two-word term everywhere**; a bare "gate" is ambiguous and the reader cannot
+  tell which one you meant.
+
+- **`artefact` vs `artifact`.** Core Terms makes `artefact` canonical, and for pipeline outputs it
+  is. But the toolchain's own code says `artifact_root` and "artifact dir" (17 uses in
+  `scripts/setup_project_ai.py` alone), and those are API names that cannot be respelled without
+  a breaking change. So: **artefact** in pipeline prose and field names; **artifact dir /
+  `artifact_root`** when naming the `.caddis/` directory mechanism. Do not "fix" one into the other.
+
+- **`skill` means two things across harnesses.** In the pool it is
+  `.github/skills/<category>/<name>/SKILL.md`. But agy CONVERTS commands into skills at install
+  time, so `/caddis:catchup` ships as a command and arrives as an agy skill. A skill count that
+  disagrees between two agents is usually this, not a bug.

package/bundles/antigravity-plugin/caddis_statusline.py

@@ -292,6 +292,42 @@ def ram_facts():
     return None
 
 
+def record_context(cwd: str, pct: float) -> None:
+    """Cache the runtime context figure for tools that never see the statusline payload.
+
+    Claude Code hands `context_window.used_percentage` to the statusline and to NOTHING else.
+    `/caddis:spawn-session` must refuse above 95% (008 section 7a) and runs as a plain bash
+    command, so without this it would have to ask the model to estimate its own usage — which
+    is the one thing that section forbids, because the faculty being gated is the faculty
+    doing the reporting.
+
+    Only writes when the value CHANGED, so an idle statusline does not rewrite a file on every
+    render. Only writes where `.caddis/` already exists, so cd-ing into an unrelated folder
+    never scatters artifact dirs. Fail-open and silent: a status line must never break a
+    prompt, and this is the least important thing it does.
+    """
+    try:
+        if not cwd:
+            return
+        art = os.path.join(cwd, ".caddis")
+        if not os.path.isdir(art):
+            return
+        target = os.path.join(art, "context-window.json")
+        payload = {"used_percentage": round(float(pct), 1), "at": int(time.time())}
+        try:
+            with open(target, encoding="utf-8") as fh:
+                if json.load(fh).get("used_percentage") == payload["used_percentage"]:
+                    return
+        except Exception:
+            pass
+        tmp = target + ".tmp"
+        with open(tmp, "w", encoding="utf-8") as fh:
+            json.dump(payload, fh)
+        os.replace(tmp, target)
+    except Exception:
+        pass
+
+
 def relay_present(cwd: str) -> bool:
     """A parked resume pointer exists for this repo. `.caddis/relay.md` is canonical;
     a bare `relay.md` at the root is the pre-rename legacy location."""
@@ -428,6 +464,7 @@ def render_claude(data: dict, cfg: dict) -> str:
             used = as_int(cw.get("total_input_tokens"))
         max_tokens = as_int(cw.get("context_window_size"))
         pct = float(as_int(cw.get("used_percentage")))
+        record_context(cwd, pct)  # feeds /caddis:spawn-session's 95% gate; see record_context
         parts.append(context_segment(c, cfg, used, max_tokens, pct))
         loud = cached_segment(c, cfg, cached)
         if loud:

package/bundles/antigravity-plugin/plugin.json

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

@@ -31,9 +31,12 @@ Usage:
 from __future__ import annotations
 
 import argparse
+import json
 import re
+import os
 import subprocess
 import sys
+import time
 from dataclasses import dataclass, field
 from pathlib import Path
 
@@ -101,9 +104,37 @@ class DocFindings:
     stale_prone: list[tuple[int, str]] = field(default_factory=list)
     historical: list[tuple[int, str]] = field(default_factory=list)
     missing_paths: list[str] = field(default_factory=list)
+    # A THIRD refusing tier, kept separate from stale_prone so the message can say something
+    # different. A stale hash is an accident the successor will notice; a stored answer key
+    # defeats the exercise SILENTLY — it certifies a reader who understood nothing.
+    answer_key: list[tuple[int, str]] = field(default_factory=list)
 
     def ok(self) -> bool:
-        return not self.stale_prone and not self.missing_paths
+        return not self.stale_prone and not self.missing_paths and not self.answer_key
+
+
+# ── answer-key detection ────────────────────────────────────────────────────────────────────
+# 008 §2: "store no answer key" was ALREADY written down, in 007 §5 — and the session that had
+# that rule available wrote one anyway, into the same file the successor reads, inside a
+# <details> block, as though that were a lock. A model reads the whole file, so the questionnaire
+# tested nothing: the successor could answer perfectly having understood none of it.
+#
+# The lesson is not "say it louder in the doc". A rule and an artefact that contradict each other
+# do not fail loudly — the artefact wins silently, because the artefact is what gets read. So the
+# check lives HERE, in the tooling, and it REFUSES rather than warns.
+#
+# Deliberately STRUCTURAL rather than semantic. A check that tries to judge whether prose reveals
+# an answer is wrong in both directions, and a check that cries wolf gets skimmed — which is how
+# the hash tier earned its two-tier split above.
+_DETAILS = re.compile(r"<details" + r"\b", re.I)
+_ANSWER_KEY_HEADING = re.compile(
+    r"^\s*(?:#{1,6}\s*|\*\*|<summary>)?\s*"
+    r"(?:answer\s*key|expected\s+answers?|correct\s+answers?|model\s+answers?|"
+    r"answers?\s*[-—]\s*for\s+the)",
+    re.I,
+)
+# `Q3: ... A: ...` — a question and its answer on one line.
+_INLINE_ANSWER = re.compile(r"\bQ\s*\d{1,2}\b.*?\b(?:A|Ans|Answer)\s*[:.\)]", re.I)
 
 
 _DOC_PATH = re.compile(r"`([^`\s<>{}*?]+?\.(?:md|py|ts|tsx|json|ya?ml|sh|ps1|html|toml|sql))`")
@@ -124,6 +155,21 @@ def check_document(text: str, repo_root: Path | None = None) -> DocFindings:
         if line.lstrip().startswith("```"):
             in_fence = not in_fence
             continue
+        # These three run BEFORE the fence exemption and are not subject to it. A fence exempts
+        # a hash because quoting one there is the cure; an answer key inside a fence is still an
+        # answer key, and a template showing `Q1: ... A: ...` is precisely the shape that teaches
+        # the next author to fill it in.
+        if _DETAILS.search(line):
+            out.answer_key.append((n, "<details> block — a rendering hint, not a lock. The child "
+                                      "reads the whole file. Move whatever it hides out of any "
+                                      "document the successor is told to open"))
+        if _ANSWER_KEY_HEADING.search(line):
+            out.answer_key.append((n, "reads as an answer key. It must not exist in a file the "
+                                      "examinee can reach — re-derive each answer from the repo "
+                                      "at validation time instead"))
+        if _INLINE_ANSWER.search(line):
+            out.answer_key.append((n, "a question and its answer on one line. The questions may "
+                                      "ship; the answers may not"))
         if _is_exempt(line, in_fence):
             continue
         for m in _HASH.finditer(line):
@@ -155,23 +201,72 @@ def check_document(text: str, repo_root: Path | None = None) -> DocFindings:
 
 # ── refusals ────────────────────────────────────────────────────────────────────────────────
 
+# ── the context gate (008 section 7a) ───────────────────────────────────────────────────────
+# REFUSE above 95%, do not warn. The thing that degrades first is exactly the thing this command
+# depends on: 007 section 1 names the failure as confident recall of SUPERSEDED facts, not
+# forgetting. A handover written from a nearly-full context is written by the failing faculty, and
+# it comes out fluent, cited and wrong. A warning does not help, because the agent that most needs
+# to heed it is the one least able to judge that it should.
+#
+# The costs are not symmetric either. Refusing early costs one session's remaining headroom.
+# A confident wrong handover costs the successor's whole session plus everything built on the
+# error, and is not discovered until much later, if at all.
+CONTEXT_REFUSE_ABOVE = 95.0
+CONTEXT_NOTE_ABOVE = 85.0
+# Generous on purpose. The cached figure can only be a LOWER bound — context goes up, never down —
+# so an old reading that already says "over 95" is still a valid refusal, and one that says 90 may
+# really be higher. Staleness is reported rather than silently trusted.
+CONTEXT_MAX_AGE_S = 900
+
+
+def read_context_pct(repo_root: Path) -> tuple[float | None, str]:
+    """(percentage, provenance) from the statusline's cache, or (None, why not).
+
+    Written by `caddis_statusline.record_context`. Claude Code gives the figure to the status
+    line and to nothing else, so this file is the only runtime-sourced number a plain command
+    can reach.
+    """
+    target = repo_root / ART / "context-window.json"
+    try:
+        raw = json.loads(target.read_text(encoding="utf-8"))
+        pct = float(raw["used_percentage"])
+        age = max(0, int(time.time()) - int(raw.get("at", 0)))
+    except Exception:
+        return None, ("no runtime context figure at "
+                      + f"{ART}/context-window.json — run `/caddis:statusline` to install the "
+                      "status line that writes it")
+    if age > CONTEXT_MAX_AGE_S:
+        return pct, f"runtime figure, STALE by {age}s (a lower bound — the real number is >= this)"
+    return pct, f"runtime figure, {age}s old"
+
+
 @dataclass
 class Preflight:
     refusals: list[str] = field(default_factory=list)
     dirty: int = 0
     parking_open: int | None = None
+    # The context figure and where it came from. Provenance is carried, not just the number,
+    # because a self-reported figure and a runtime one are not the same evidence and the
+    # handover has to say which it had (008 section 7a: the 85-95 band must state the figure).
+    context_pct: float | None = None
+    context_source: str = ""
+    notes: list[str] = field(default_factory=list)
 
     def ok(self) -> bool:
         return not self.refusals
 
 
-def preflight(repo_root: Path) -> Preflight:
+def preflight(repo_root: Path, context_pct: float | None = None) -> Preflight:
     """Conditions under which a spawn must not happen at all.
 
     A dirty tree is the sharp one: the successor starts by pulling, so **uncommitted work is
     invisible to it**. It will then either redo that work or build on a state that does not exist.
+
+    `context_pct` is the caller's own reading, for machines with no caddis status line — see
+    _gate_context for why it can only ever tighten the gate.
     """
     p = Preflight()
+    _gate_context(p, repo_root, context_pct)
     status = _run(["git", "status", "--short"], repo_root)
     p.dirty = len([l for l in status.splitlines() if l.strip()])
     if p.dirty:
@@ -191,6 +286,58 @@ def preflight(repo_root: Path) -> Preflight:
     return p
 
 
+def _gate_context(p: Preflight, repo_root: Path, self_reported: float | None) -> None:
+    """008 section 7a: refuse above 95%, note between 85 and 95, and never silently proceed.
+
+    Two sources, and the rule between them is the whole design:
+
+      * the status line's cache — runtime-sourced, and the only such number a plain command can
+        reach, because Claude Code hands `used_percentage` to the status line and nothing else;
+      * `--context-pct`, the caller's own reading, for a machine with no caddis status line.
+
+    **A self-reported figure may only TIGHTEN the gate, never loosen it** — so the two are
+    combined with max(). That is what makes the fallback safe rather than theatre. 007 section 1
+    names the failure as confident recall by a degraded context; a self-report that can talk its
+    way THROUGH the gate is exactly that failure wearing the gate's clothes, while one that can
+    only trip it earlier cannot be gamed into a pass.
+
+    With NO figure from either source it refuses, per 008: "an unmeasurable gate that defaults to
+    proceed is not a gate". But it refuses with two ways out, because a gate that cannot be
+    satisfied on a machine without the status line would simply be switched off.
+    """
+    pct, source = read_context_pct(repo_root)
+    if self_reported is not None:
+        if pct is None or self_reported > pct:
+            pct = self_reported
+            source = "SELF-REPORTED via --context-pct, not verified against the runtime"
+        else:
+            source = source + f"; --context-pct said {self_reported:.0f}%, kept the higher figure"
+    p.context_pct, p.context_source = pct, source
+
+    if pct is None:
+        p.refusals.append(
+            "no context figure, so the 95% gate cannot be applied — and a gate that defaults to "
+            "proceed is not a gate. Either run `/caddis:statusline` (its status line caches the "
+            "runtime figure for this repo), or pass `--context-pct <n>` with the number your "
+            "harness reports. A self-reported figure is accepted and recorded as such.")
+        return
+    if pct > CONTEXT_REFUSE_ABOVE:
+        p.refusals.append(
+            f"context is {pct:.0f}% ({source}). A handover written from here would be fluent and "
+            "unreliable, which is the failure this command exists to prevent. Do this instead, "
+            "in order: (1) commit and push everything now; (2) write ONLY the task list to "
+            f"{ART}/parent-session-state.md, the smallest durable artefact and the one a task "
+            "widget loses; (3) TELL the product owner which capture steps you skipped; (4) let "
+            "the successor rebuild the relay from the repo, which beats this session's memory of "
+            "it anyway. A partial handover that SAYS it is partial is worth far more than a "
+            "complete-looking one nobody can trust.")
+        return
+    if pct > CONTEXT_NOTE_ABOVE:
+        p.notes.append(
+            f"context is {pct:.0f}% ({source}). Under the refusal line, but STATE THIS FIGURE in "
+            "the handover so the reader can weigh what it says.")
+
+
 # ── fingerprint ─────────────────────────────────────────────────────────────────────────────
 
 def fingerprint(repo_root: Path, with_tests: bool = False) -> dict:
@@ -240,6 +387,205 @@ def verify_answerable(repo_root: Path, answer_in: str, needle: str) -> tuple[boo
     return True, f"{answer_in} contains {needle!r} and is committed"
 
 
+# ── the capture order (008 section 4) ──────────────────────────────────────────────────────
+# Knowledge -> durable state -> task list -> relay -> questions. Out of sequence it produces a
+# handover that describes a state that never existed: the relay CITES the first three, so writing
+# it earlier cites things that have since moved, and questions written first test the outgoing
+# agent's MEMORY, which is the thing under suspicion.
+#
+# mtimes are the evidence. This does not check that each step was done well — nothing can — it
+# checks the one property that is mechanically knowable and that a tired session gets wrong.
+PARENT_RELAY = "parent-relay.md"
+PARENT_STATE = "parent-session-state.md"
+
+
+def _mtime(path: Path) -> float | None:
+    try:
+        return path.stat().st_mtime
+    except OSError:
+        return None
+
+
+def capture_order(repo_root: Path, spawn_id: str) -> tuple[list[str], list[str]]:
+    """(refusals, notes) on the ORDER the handover artefacts were written in.
+
+    Required: the relay and the prompt. The task list is advisory, because a session can
+    legitimately end with nothing on it — but a MISSING step must be declared, not inferred,
+    which is why it is a note rather than silence.
+    """
+    refusals: list[str] = []
+    notes: list[str] = []
+    art = repo_root / ART
+    relay, state = art / PARENT_RELAY, art / PARENT_STATE
+    prompt = repo_root / SPAWN_DIR / (spawn_id + "-prompt.md")
+
+    t_relay, t_state, t_prompt = _mtime(relay), _mtime(state), _mtime(prompt)
+    if t_relay is None:
+        refusals.append(f"no {ART}/{PARENT_RELAY} — step 4 of the capture order never happened")
+    if t_prompt is None:
+        refusals.append(f"no {SPAWN_DIR}/{spawn_id}-prompt.md — step 5 never happened")
+    if refusals:
+        return refusals, notes
+
+    if t_state is None:
+        notes.append(f"no {ART}/{PARENT_STATE}. A task widget does not survive a `/clear` and this "
+                     "project has already lost one — if the list is genuinely empty, SAY so in the "
+                     "handover rather than leaving the reader to infer it.")
+    elif t_state > t_relay:
+        refusals.append(f"{PARENT_STATE} is NEWER than {PARENT_RELAY}. The relay cites the task "
+                        "list, so a list written afterwards means the relay describes a state "
+                        "that never existed. Rewrite the relay, do not re-touch the list.")
+
+    if t_relay > t_prompt:
+        refusals.append(f"{PARENT_RELAY} is NEWER than the prompt. The questions must target what "
+                        "the relay actually says — derived from a relay that has since changed, "
+                        "they test your memory of it, which is the thing under suspicion.")
+
+    # Anything the relay quotes that moved after it was written.
+    for sub_dir in ("kb", "parking-lot"):
+        d = art / sub_dir
+        if not d.is_dir():
+            continue
+        moved = sorted(f.name for f in d.glob("*.md") if (_mtime(f) or 0) > t_relay)
+        if moved:
+            notes.append(f"{sub_dir}/ changed AFTER the relay was written: "
+                         + ", ".join(moved[:5]) + ("" if len(moved) <= 5 else ", ...")
+                         + ". The relay quotes these, so re-read them before issuing it.")
+    return refusals, notes
+
+
+# ── the handshake (008 section 3) ───────────────────────────────────────────────────────────
+# 007 routed every round trip through a human paste. Sessions can message each other now, so the
+# human is an approver rather than a transport — but only where a transport exists.
+#
+# THE CHILD INITIATES. It cannot message until it has answers, so the message itself is evidence
+# it did the reading. But child-initiated ALONE leaves the worst failure invisible: a successor
+# that skips the gate and just starts working produces silence, and silence is indistinguishable
+# from "still reading". So the parent holds a timeout and CHASES.
+#
+# None of that can be enforced by prose. Section 2 of 008 is the proof: a rule written in a
+# document lost to the artefact that contradicted it, within a day, in this very command. So the
+# state lives in a file and `close` refuses to let the parent finish while the handshake is open.
+# "Closing on an unanswered handshake is the same as never running one."
+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"}
+
+
+def detect_transport(env: dict | None = None) -> tuple[str, str]:
+    """('message' | 'paste', why) — tests the CAPABILITY, not the vendor.
+
+    `SendMessage` is Claude Code only; the harness also ships an `agy/` directory and targets
+    Codex, so a Claude-only command would simply not run on two of three targets. That makes the
+    paste path a supported route, not a degraded one.
+
+    The signal is `CLAUDE_CODE_MESSAGING_SOCKET`, which IS the cross-session transport — a peer
+    message arrives addressed from that socket. Keying on the socket rather than on "is this
+    Claude Code" means a runtime that gains messaging later works with no change here, and a
+    Claude Code with messaging switched off correctly falls back instead of failing at the moment
+    it tries to send.
+    """
+    env = os.environ if env is None else env
+    if env.get("CLAUDE_CODE_MESSAGING_SOCKET"):
+        return "message", "CLAUDE_CODE_MESSAGING_SOCKET is set — peers are reachable directly"
+    if env.get("CLAUDECODE"):
+        return "paste", ("Claude Code, but no messaging socket — the transport is off or this "
+                         "build predates it. The human carries the round trip.")
+    return "paste", ("no messaging transport (agy, Codex or a plain shell). The human carries "
+                     "the round trip — this is a supported path, not a broken one.")
+
+
+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:
+    """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."""
+    chosen, why = detect_transport()
+    if transport != "auto":
+        chosen, why = transport, "forced with --transport"
+    state = {
+        "id": spawn_id,
+        "state": HANDSHAKE_STATES[0],
+        "transport": chosen,
+        "transport_reason": why,
+        "opened_at": int(time.time()),
+        "history": [],
+    }
+    path = _handshake_path(repo_root, spawn_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(state, indent=2) + chr(10), encoding="utf-8")
+    return state
+
+
+def handshake_read(repo_root: Path, spawn_id: str) -> dict | None:
+    try:
+        return json.loads(_handshake_path(repo_root, spawn_id).read_text(encoding="utf-8"))
+    except Exception:
+        return None
+
+
+def handshake_record(repo_root: Path, spawn_id: str, event: 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."""
+    state = handshake_read(repo_root, spawn_id)
+    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())})
+    state["state"] = target
+    _handshake_path(repo_root, spawn_id).write_text(
+        json.dumps(state, indent=2) + chr(10), encoding="utf-8")
+    return state, ""
+
+
+def handshake_chase_due(state: dict, now: int | None = None) -> int:
+    """Seconds overdue for a chase, or 0. Only meaningful while awaiting answers.
+
+    A chase is not a reminder. It should carry two FRESH questions, which cannot have been
+    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]:
+        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)
+
+
+def handshake_close(repo_root: Path, spawn_id: str) -> tuple[bool, str]:
+    """May the parent stop now? The lifecycle rule, made mechanical.
+
+    A handover nobody has read is not a handover, it is a file. Grading RE-DERIVES, so it audits
+    the document as well as the reader — in the manual run that pass found a defect in the
+    parent's own handover. `/clear` in the parent's terminal destroys the only thing that can do
+    that, so the parent must outlive the handshake.
+
+    NOTE the distinction this makes explicit, because two documents look like they disagree:
+    `spawn-hub` says the outgoing session STOPS WRITING the moment the prompt is issued (two
+    sessions committed to one repo concurrently and one's work landed inside the other's commit).
+    008 says the parent is not CLOSED until the child passes. Alive is not writing. Both hold.
+    """
+    state = handshake_read(repo_root, spawn_id)
+    if state is None:
+        return False, (f"no handshake recorded for {spawn_id}. If one was run, it was not "
+                       "recorded, and an unrecorded handshake cannot be distinguished from none.")
+    if state["state"] != HANDSHAKE_STATES[-1]:
+        return False, (f"handshake is at `{state['state']}`, not `acknowledged`. The parent stays "
+                       "ALIVE until the child confirms it has the verdict — closing on an "
+                       "unanswered handshake is the same as never running one. (It may stop "
+                       "WRITING to the repo now; that is a different rule and both hold.)")
+    return True, "acknowledged — the parent may close"
+
+
 def main(argv: list[str] | None = None) -> int:
     ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
     sub = ap.add_subparsers(dest="cmd", required=True)
@@ -248,9 +594,23 @@ def main(argv: list[str] | None = None) -> int:
         s.add_argument("--repo-root", default=".")
         if name == "fingerprint":
             s.add_argument("--with-tests", action="store_true")
+        else:
+            s.add_argument("--context-pct", type=float, default=None,
+                           help="your own context-usage reading, 0-100, for a machine with no "
+                                "caddis status line. Only ever tightens the gate: the higher of "
+                                "this and the cached runtime figure wins.")
     c = sub.add_parser("check")
     c.add_argument("--doc", required=True)
     c.add_argument("--repo-root", default=".")
+    o = sub.add_parser("capture-check")
+    o.add_argument("--id", required=True)
+    o.add_argument("--repo-root", default=".")
+    h = sub.add_parser("handshake")
+    h.add_argument("action", choices=["open", "status", "record", "close"])
+    h.add_argument("--id", required=True)
+    h.add_argument("--repo-root", default=".")
+    h.add_argument("--event", choices=sorted(_EVENT_STATE))
+    h.add_argument("--transport", choices=["auto", "message", "paste"], default="auto")
     q = sub.add_parser("verify-question")
     q.add_argument("--answer-in", required=True)
     q.add_argument("--needle", required=True)
@@ -259,9 +619,12 @@ def main(argv: list[str] | None = None) -> int:
     root = Path(a.repo_root).resolve()
 
     if a.cmd == "preflight":
-        p = preflight(root)
+        p = preflight(root, context_pct=a.context_pct)
+        for note in p.notes:
+            print(f"  note  {note}")
         if p.ok():
-            print(f"[spawn] ready — clean tree, {p.parking_open} open parking-lot item(s)")
+            ctx = f", context {p.context_pct:.0f}%" if p.context_pct is not None else ""
+            print(f"[spawn] ready — clean tree, {p.parking_open} open parking-lot item(s){ctx}")
             return EXIT_OK
         sys.stderr.write("[spawn] REFUSING to spawn:\n")
         for r in p.refusals:
@@ -284,13 +647,71 @@ def main(argv: list[str] | None = None) -> int:
             print(f"[spawn] {doc.name} passes round 0 — nothing stale-prone, every path exists")
             return EXIT_OK
         sys.stderr.write(f"[spawn] {doc.name} FAILS round 0:\n")
+        for n, msg in f.answer_key:
+            sys.stderr.write(f"    line {n}: ANSWER KEY — {msg}" + chr(10))
         for n, msg in f.stale_prone:
             sys.stderr.write(f"    line {n}: {msg}\n")
         for p_ in f.missing_paths:
             sys.stderr.write(f"    names a path that does not exist: {p_}\n")
         sys.stderr.write("  A claim that cannot be re-derived does not go in the handover.\n")
+        if f.answer_key:
+            sys.stderr.write("  And an answer the examinee can read is not a check. This REFUSES "
+                             "rather than warns because the rule was already written down, in "
+                             "007 section 5, and a session that had it broke it within a day."
+                             + chr(10))
         return EXIT_REFUSED
 
+    if a.cmd == "capture-check":
+        refusals, notes = capture_order(root, a.id)
+        for n in notes:
+            print(f"  note  {n}")
+        if not refusals:
+            print("[spawn] capture order holds — relay after the task list, questions after both")
+            return EXIT_OK
+        sys.stderr.write("[spawn] capture order is WRONG:" + chr(10))
+        for r in refusals:
+            sys.stderr.write("    " + r + chr(10))
+        sys.stderr.write("  Out of sequence, a handover describes a state that never existed."
+                         + chr(10))
+        return EXIT_REFUSED
+
+    if a.cmd == "handshake":
+        if a.action == "open":
+            st = handshake_open(root, a.id, a.transport)
+            print(f"[spawn] handshake {a.id} open — transport `{st['transport']}` "
+                  f"({st['transport_reason']})")
+            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 "
+                      "broken.")
+            return EXIT_OK
+        st = handshake_read(root, a.id)
+        if st is None:
+            sys.stderr.write(f"[spawn] no handshake for {a.id}" + chr(10))
+            return EXIT_REFUSED
+        if a.action == "status":
+            over = handshake_chase_due(st)
+            print(f"[spawn] {a.id}: {st['state']} via {st['transport']}")
+            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.")
+            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)
+            if err:
+                sys.stderr.write("[spawn] " + err + chr(10))
+                return EXIT_REFUSED
+            print(f"[spawn] {a.id}: {st['state']}")
+            return EXIT_OK
+        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
+
     ok, msg = verify_answerable(root, a.answer_in, a.needle)
     (print if ok else sys.stderr.write)(f"[spawn] {msg}" + ("" if ok else "\n"))
     return EXIT_OK if ok else EXIT_REFUSED

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

@@ -292,6 +292,42 @@ def ram_facts():
     return None
 
 
+def record_context(cwd: str, pct: float) -> None:
+    """Cache the runtime context figure for tools that never see the statusline payload.
+
+    Claude Code hands `context_window.used_percentage` to the statusline and to NOTHING else.
+    `/caddis:spawn-session` must refuse above 95% (008 section 7a) and runs as a plain bash
+    command, so without this it would have to ask the model to estimate its own usage — which
+    is the one thing that section forbids, because the faculty being gated is the faculty
+    doing the reporting.
+
+    Only writes when the value CHANGED, so an idle statusline does not rewrite a file on every
+    render. Only writes where `.caddis/` already exists, so cd-ing into an unrelated folder
+    never scatters artifact dirs. Fail-open and silent: a status line must never break a
+    prompt, and this is the least important thing it does.
+    """
+    try:
+        if not cwd:
+            return
+        art = os.path.join(cwd, ".caddis")
+        if not os.path.isdir(art):
+            return
+        target = os.path.join(art, "context-window.json")
+        payload = {"used_percentage": round(float(pct), 1), "at": int(time.time())}
+        try:
+            with open(target, encoding="utf-8") as fh:
+                if json.load(fh).get("used_percentage") == payload["used_percentage"]:
+                    return
+        except Exception:
+            pass
+        tmp = target + ".tmp"
+        with open(tmp, "w", encoding="utf-8") as fh:
+            json.dump(payload, fh)
+        os.replace(tmp, target)
+    except Exception:
+        pass
+
+
 def relay_present(cwd: str) -> bool:
     """A parked resume pointer exists for this repo. `.caddis/relay.md` is canonical;
     a bare `relay.md` at the root is the pre-rename legacy location."""
@@ -428,6 +464,7 @@ def render_claude(data: dict, cfg: dict) -> str:
             used = as_int(cw.get("total_input_tokens"))
         max_tokens = as_int(cw.get("context_window_size"))
         pct = float(as_int(cw.get("used_percentage")))
+        record_context(cwd, pct)  # feeds /caddis:spawn-session's 95% gate; see record_context
         parts.append(context_segment(c, cfg, used, max_tokens, pct))
         loud = cached_segment(c, cfg, cached)
         if loud:

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

@@ -897,6 +897,8 @@ agent-log.jsonl
 relay.md
 relay/
 session-state.md
+session-state/
+context-window.json
 PROJECT-FACTS.md
 memory.jsonl
 """
@@ -919,6 +921,10 @@ English does not, and marks which already have an entry:
 It cannot write the definitions - only a person or the model reading the code can say what
 a coined word MEANS here. Run `/caddis:glossary` to have them drafted, or write them.
 
+This file is for YOUR project's vocabulary. caddis's own coined words - pool, relay, drift,
+export target - are defined separately in `CADDIS-GLOSSARY.md` at the plugin root, which also
+serves as a worked example of what a good entry looks like. Do not copy those terms in here.
+
 | Term | Definition | DO NOT USE |
 |---|---|---|
 | _example_ | Replace this row. Say what the word means HERE, and why the ordinary reading is wrong. | the synonyms that cause confusion |

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

@@ -85,6 +85,7 @@
 | Park | `park/` | File a future-work item in the one backlog — .caddis/parking-lot/ — or list what is open |
 | Prd | `prd/` | Capture requirements through structured discovery and write a PRD |
 | Resume | `resume/` | Pop the most recently parked workstream off the stack and resume it at its exact resume point |
+| Review | `review/` | Review someone else's OPEN pull request end to end — what changed, what CI says, what is risky — then approve or request changes. Never approves on its own. |
 | Ship | `ship/` | Commit, push, and monitor the deploy pipeline (auto-detects Gitea, GitHub Actions, or local-only) |
 | Ship Merge | `ship-merge/` | Merge an already-green, already-reviewed PR behind an explicit deploy-confirm, monitor the deploy, validate prod, then clean up the branch — only on green. |
 | Ship Pr | `ship-pr/` | Open a reviewed PR for the current feature branch — rebase-safe push, PR create/update, monitor CI, STOP at green. Never merges, never deploys (that's /ship-merge). |

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

@@ -13,9 +13,14 @@ be a coin toss every time.
 
 ## Read these, in this order, and stop as soon as you can answer
 
-1. **`.caddis/session-state.md`** — the primary source. The `Stop` hook rewrites it at the end of
-   every turn, so it is current even when the session ended abruptly and nobody ran `/handoff`.
-   It holds the last real request, the task list with statuses, and the files touched.
+1. **`.caddis/session-state/<session-id>.md`** — the primary source; read the NEWEST. The `Stop`
+   hook rewrites one per session at the end of every turn, so it is current even when the session
+   ended abruptly and nobody ran `/handoff`. It holds the last real request, the task list with
+   statuses, and the files touched. Repos that have not stopped a session since 2026-09-08 have a
+   single `.caddis/session-state.md` instead; read that when the directory is absent.
+   **Check the `Session:` id in the header.** Sessions share working trees here, so the newest file
+   can belong to a live PEER rather than to the session you are catching up on — if the id is not
+   the one you are resuming, say so instead of reporting its work as yours.
 2. **`.caddis/relay.md`** — only refreshed by `/handoff`, so it may be days behind, but it carries
    what the state file cannot: the agreed **next step** and the open blockers.
 3. **The current turn's own context**, if this session has already done work. What you have done

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

@@ -52,6 +52,10 @@ Each row gets three things:
 | **Definition** | What it means HERE, and — where it helps — why the ordinary reading misleads. Say the thing a newcomer would get wrong. |
 | **DO NOT USE** | The synonyms actually causing confusion in this repo. Leave blank rather than inventing some. |
 
+**A worked example ships with caddis.** `CADDIS-GLOSSARY.md` at the plugin root defines caddis's
+own coined vocabulary the same way — read a few entries before writing yours. It is caddis's
+words, not this project's: never copy its terms into a project glossary.
+
 Good: *"pool — the single source of every shipped resource, in `.github/`. Everything installed is EXPORTED from it; nothing is authored in a bundle."*
 
 Bad: *"pool — a pool of resources."*

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

@@ -0,0 +1,100 @@
+---
+name: review
+description: Review someone else's OPEN pull request end to end — what changed, what CI says, what is risky — then approve or request changes. Never approves on its own.
+---
+
+# /caddis:review — review an open PR, then decide
+
+Review pull request **$ARGUMENTS** and walk the operator to an approve-or-not decision.
+
+> **This is the only caddis review surface aimed at a PULL REQUEST.** The others review a local
+> diff: `/caddis:gate-review` (adversarial, same vendor), `/caddis:cross-review` (a different
+> vendor's model). `/caddis:ship-pr` and `/caddis:ship-merge` create and merge PRs. This one is for
+> the case none of those covers — somebody else has opened a PR and you have to decide about it.
+>
+> Do not reimplement the review itself. Gather the context, then hand the diff to
+> `/caddis:gate-review` (or Claude Code's native `/code-review`, which is better where it exists).
+
+## Absolute rule
+
+**Never approve, request changes, merge, or close on the operator's behalf.** Present the evidence
+and the exact command; the human runs it. An approval is the one human judgement in the pipeline —
+a review tool that also approves has removed the thing it was built to protect.
+
+## 1. Resolve the PR
+
+`$ARGUMENTS` is a PR number, optionally followed by `owner/repo`. With no repo, use the current
+directory's `origin`. If the number is missing, list the open PRs and stop.
+
+```bash
+gh pr view <n> --repo <owner/repo> --json number,title,author,state,isDraft,mergeStateStatus,reviewDecision,baseRefName,headRefName,additions,deletions,changedFiles,url
+```
+
+**Stop and say so, before reviewing anything**, if:
+- the PR is **merged or closed** — there is nothing to decide;
+- it is a **draft** — say so and ask whether to continue;
+- **the operator is the author.** GitHub does not allow approving your own PR. Say it plainly, and
+  say the alternatives: have someone else approve it, or merge with an admin bypass
+  (`gh pr merge <n> --squash --admin`). Do not silently produce a review they cannot submit.
+
+## 2. Gather what the decision needs
+
+Four things, and report them even when they are boring — "CI is green" is information:
+
+```bash
+gh pr checks <n> --repo <owner/repo>            # every check and its state
+gh pr diff  <n> --repo <owner/repo>             # the change itself
+gh pr view  <n> --repo <owner/repo> --comments  # review comments, and any bot review
+```
+
+If an automated review has already commented, **read it and say whether you agree**. Two reviews
+that disagree is a finding; two that agree is worth stating once, not twice.
+
+`mergeStateStatus` explains a blocked PR without guessing: `BLOCKED` (needs a review),
+`BEHIND` (needs *Update branch*), `UNSTABLE` (a check failed), `DIRTY` (conflicts).
+
+## 3. Review the diff
+
+Hand it to `/caddis:gate-review` — or the native `/code-review` on Claude Code. Then, on top of its
+verdict, check the things that have actually cost this fleet time, because a generic reviewer will
+not know to look:
+
+- **A gate that cannot fail.** A check whose failure path cannot execute — piped to `Out-Null`,
+  wrapped in a `catch{}` a native non-zero exit can never trigger, or asserting something too broad
+  to attribute. It manufactures confidence. Worse than no check.
+- **A wall-clock assertion.** A timing threshold on a shared runner measures load, not the code.
+  Assert ordering instead.
+- **Staged directories.** `git add -A` / `git add .` sweeps in files nobody reviewed.
+- **CI shell assumptions.** The runner may be Windows PowerShell 5.1, where a native command's
+  stderr becomes a terminating error under `$ErrorActionPreference='Stop'`, and where `Should -Be`
+  (Pester 4 syntax) fails on a Pester 3 runner.
+- **Deploy-script changes.** If the pipeline runs the deploy script from a checkout it also updates,
+  the change does not take effect on the deploy that delivers it. Budget two deploys.
+- **Verification by proxy.** An HTTP 200 or a version string is not proof a page renders.
+- **Credentials.** A token scoped to the wrong host; a permission raised to make a test pass; a
+  secret in a URL where git will echo it into a log.
+- **A doc the change makes untrue.** Comments and runbooks that were accurate until this diff.
+
+## 4. Report, then hand over
+
+Lead with the verdict. Keep it short enough to read before deciding:
+
+- **What this PR does** — one or two sentences, not a file list.
+- **Blocking issues** — each with file, line, and why it matters. None is a valid answer, and say it.
+- **Should-fix / nits** — grouped, brief.
+- **CI** — green, red, or still running. Name the failing check.
+- **Merge state** — and what would clear it.
+
+Then print the exact commands, and stop:
+
+```bash
+# approve
+gh pr review <n> --repo <owner/repo> --approve
+gh pr merge  <n> --repo <owner/repo> --squash --delete-branch
+
+# or ask for changes
+gh pr review <n> --repo <owner/repo> --request-changes --body "..."
+```
+
+**If you found a blocking issue, say so in the verdict line** rather than burying it under the
+summary. The operator should be able to read the first line and know whether to keep reading.

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

@@ -186,6 +186,27 @@ Then write the judgement half yourself. It must contain:
    - name **one thing a green automated check does NOT prove**, with the example that taught it
    - **verify the tree independently** — `git fetch`, count divergence, and `git status`/diff any dirty
      file before treating it as authority
+   > **THE NEW HUB MUST NOT MARK ITS OWN SELF-CHECK.** Until 2026-09-08 nothing graded these
+   > answers: this command does not start the new session, so nothing routed them back. A
+   > self-marked exam tests willingness, not comprehension. Run the handshake instead — the
+   > incoming Hub answers, **you re-derive each answer from the files**, then you send the
+   > verdict:
+   >
+   > ```bash
+   > python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" handshake open   --id <id>
+   > python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" handshake status --id <id>
+   > python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" handshake record --id <id> --event answers
+   > python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" handshake close  --id <id>
+   > ```
+   >
+   > It reports whether this runtime can message a peer at all and falls back to the paste route
+   > on agy and Codex, which have no `SendMessage`. `close` refuses until the incoming Hub has
+   > acknowledged the verdict. See `/caddis:spawn-session` for the full direction table and the
+   > chase rule.
+   >
+   > **This does not soften the single-writer rule below.** You stay ALIVE to grade; you stop
+   > WRITING when the prompt is issued. Both hold.
+
 4. **At least one question whose naive answer is WRONG.** This is the load-bearing part. A Hub that
    only skimmed must fail *visibly* rather than silently.
 

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

@@ -29,6 +29,51 @@ and the active plan).
 
 ---
 
+## The capture ORDER — it is an order, not a list
+
+**Out of sequence, you produce a handover that describes a state that never existed.**
+
+| # | Step | Why it must be here |
+|---|---|---|
+| 1 | **Capture the knowledge** — KB notes for anything that generalises | FIRST, while the reasoning is still in context. Written last it becomes a summary of a summary |
+| 2 | **Update the durable state** — the register, the parking lot | These are the authority. The relay quotes them, so they must be true before it does |
+| 3 | **Write the TASK LIST to a file** | A task widget does not survive a `/clear`. This project has already lost one |
+| 4 | **Write the relay** — what happened, who owns what, what is blocked | It CITES 1-3. Written earlier, it cites things that have since moved |
+| 5 | **Derive the questions** | LAST. They must target what steps 1-4 actually say. Questions written first test **your memory**, which is the thing under suspicion |
+
+Named, so a fresh session knows what to open with no prompt engineering:
+
+```
+.caddis/parent-relay.md            what happened, who owns what, what blocks
+.caddis/parent-session-state.md    the task list
+```
+
+**`parent-` rather than overwriting `relay.md`:** the live relay belongs to the WORK and outlives
+any one session. A handover is a snapshot.
+
+> **Do not confuse `.caddis/parent-session-state.md` with `.caddis/session-state/`.** The names
+> are close and the handling is opposite. The directory is written by the Stop hook every turn,
+> one file per session id, and is **gitignored** — a recovery aid. The `parent-` file is written
+> by you, once, deliberately, and is **committed** — a handover artefact. Reaching for the wrong
+> one means either handing over an auto-generated stub, or committing conversation text.
+
+Check the order before you issue anything:
+
+```bash
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" capture-check --id <id>
+```
+
+It compares write times, which is the one property here that is mechanically knowable. It cannot
+tell you a step was done *well* — nothing can — but it refuses a relay written before the task
+list it cites, and questions derived before the relay they are supposed to target. It also flags
+any KB note or register item that changed **after** the relay was written, because the relay
+quotes those and they have since moved.
+
+**A step that produced nothing is a note, not a failure — but you must SAY it produced nothing.**
+A missing task list that the reader has to infer is worse than one declared empty.
+
+---
+
 ## Round 0 — validate your OWN handover. No relay trip.
 
 **Do this before writing the prompt.** It is the cheapest round and the one this whole command is
@@ -44,6 +89,33 @@ python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" fingerprint --with-tests
 `preflight` **refuses on a dirty tree** — the successor pulls, so uncommitted work is invisible to
 it and it will either redo that work or build on a state that does not exist. Commit first.
 
+### It also refuses above 95% context
+
+**A refusal, not a warning.** Under 85% it runs normally; between 85% and 95% it runs and prints
+the figure, which you must then **state in the handover** so the reader can weigh it.
+
+Why a refusal: the thing that degrades first is the thing this command depends on. The failure is
+not forgetting, it is **confident recall of superseded facts** — so a handover written from a
+nearly-full context comes out fluent, cited and wrong. A warning cannot help, because the agent
+that most needs to heed it is the one least able to judge that it should. The costs are not
+symmetric either: refusing early costs this session's remaining headroom, while a confident wrong
+handover costs the successor's whole session and everything built on the error.
+
+**Where the number comes from.** Claude Code hands `context_window.used_percentage` to the status
+line and to nothing else, so the caddis status line caches it per repo and `preflight` reads it
+back. **No status line on this machine?** Pass your own reading:
+
+```bash
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" preflight --context-pct 72
+```
+
+**A self-reported figure may only tighten the gate, never loosen it** — the higher of the two
+always wins, so it can refuse earlier but can never talk its way through. That asymmetry is what
+makes the fallback safe: the faculty being gated is the faculty doing the reporting.
+
+With **no figure from either source, it refuses** — an unmeasurable gate that defaults to proceed
+is not a gate — and the refusal names both ways out rather than leaving you stuck.
+
 ### Capture from the repo, never from recall
 
 ```bash
@@ -102,7 +174,7 @@ python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" verify-question \
 A question whose answer is not written down tests memory — the thing being replaced. It is not a
 harder question; it is the old failure wearing an exam's clothes.
 
-### Store NO answer key
+### Store NO answer key — and `check` now REFUSES one
 
 Do not write `<id>-key.md`. Two reasons, and the second is the one that matters:
 
@@ -110,13 +182,109 @@ Do not write `<id>-key.md`. Two reasons, and the second is the one that matters:
 2. **A stored key freezes your belief at capture time.** If you were wrong, the key is wrong, and
    the check certifies the error.
 
+**This rule is no longer only written down.** It was written down before — in `007` §5, in these
+words — and a session that had it available wrote a key anyway: into the file the successor reads,
+inside a collapsed `details`/`summary` block, as though that were a lock. A model reads the whole file, so the
+questionnaire tested nothing.
+
+`caddis_spawn.py check` now **refuses** three shapes, and does not merely warn:
+
+| Refused | Why |
+|---|---|
+| any collapsed `details` element | a rendering hint for a browser, not an access control |
+| an answer-key heading | `ANSWER KEY`, `Expected answers`, `Correct answers`, `answers — for the …` |
+| a numbered question and its answer on the same line | the questions may ship; the answers may not |
+
+Questions on their own still pass — a check that blocked those would be switched off within a day.
+The check is structural, not semantic, on purpose: judging whether prose *reveals* an answer is
+wrong in both directions, and a check that cries wolf gets skimmed.
+
+**The general class is bigger than this command.** A rule and an artefact that contradict each
+other do not fail loudly. The artefact wins, silently, because the artefact is what gets read. So
+put the check in the tooling, never in a document that says the tooling should have one.
+
 **Re-derive each answer from the repo at validation time instead.** That validates the DOCUMENT and
 the READER at once — which is exactly what `.caddis/parking-lot/done/004-*` said was missing, where
 a successor passed a thirteen-question check on a handover containing four factual errors.
 
+### The handshake — who sends what, and in which direction
+
+007 routed every round trip through a human paste. Sessions can message each other now, so the
+human becomes an approver rather than a transport — **where a transport exists.** Open the
+handshake when you issue the prompt, not when the child replies:
+
+```bash
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" handshake open --id <id>
+```
+
+It reports which route you are on. **`SendMessage` is Claude Code only** — the harness ships an
+`agy/` directory and targets Codex — so detection tests `CLAUDE_CODE_MESSAGING_SOCKET`, the
+transport itself, rather than the vendor. **The paste route is a supported path, not a broken
+one.** On it, say so in the printed instructions, or the user watches nothing happen and concludes
+the command is broken.
+
+| Direction | When |
+|---|---|
+| **child → parent** | **Primary.** As soon as it has answers. It cannot message before it has them, so the message IS evidence it did the reading |
+| **parent → child** | **A chase**, after the timeout, or whenever the product owner asks |
+| **parent → child** | **The verdict.** Always, and always after re-deriving |
+| child → parent | An acknowledgement, so the parent knows it may close |
+
+**The parent chases, because child-initiated alone cannot see the worst failure.** A successor
+that skips the gate and starts working produces silence — and silence is indistinguishable from
+"still reading". Check it:
+
+```bash
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" handshake status --id <id>
+```
+
+**A chase carries two FRESH questions, not just a reminder.** A reminder invites a hurried reply.
+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.
+
+Record each step, and the parent may not finish until the child has acknowledged:
+
+```bash
+... handshake record --id <id> --event answers    # the child replied
+... handshake record --id <id> --event verdict    # you replied, after re-deriving
+... handshake record --id <id> --event ack        # the child confirmed
+... handshake close  --id <id>                    # REFUSES unless acknowledged
+```
+
+**`close` refuses on an open handshake, and that is the point.** A handover nobody has read is not
+a handover, it is a file — and grading RE-DERIVES, so it audits the document as well as the
+reader. In the manual run that pass found a defect in the parent's own handover. `/clear` in your
+terminal destroys the only thing that can do that.
+
+> **You stay ALIVE. You stop WRITING.** `/caddis:spawn-hub` carries a single-writer rule — the
+> outgoing session stops writing to the repository the moment the prompt is issued, because two
+> sessions committed to one repo concurrently and one's work landed inside the other's commit.
+> That is a different rule from this one and **both hold.** Said no other way, a reader reconciles
+> them by closing the parent early, which removes the grader.
+
+Note the handshake file lands in `.caddis/spawn-session/`, so commit it with the others before
+re-running `preflight`, which refuses on a dirty tree.
+
+### Tell the child it does not own the tree
+
+**Say this in the prompt.** A fresh session's instinct on seeing a dirty tree is to tidy it, and
+you are still in that tree.
+
+> While both sessions are live, do **not** run `git checkout`, `switch`, `stash`, `reset`,
+> `rebase` or `clean`. A branch switch is visible to every session in this working tree and
+> carries or destroys the other's uncommitted work. For parallel work, add a `git worktree` off
+> `origin/main` instead of checking out here. Commit early — only committed objects are safe
+> from another session's checkout.
+
+The harness prints a live-peer warning at SessionStart when it can see one, but it **under-reports
+by design**: a peer that has not finished a turn has written no state yet. No warning means no
+evidence of a peer, not "you are alone". `git worktree list` finds what it cannot.
+
+See `.caddis/kb/shared-worktree-branch-switch.md` for detection and the recovery pattern.
+
 ### What the child sends back
 
-Three lines, carried by the user:
+Three lines — messaged directly, or carried by the user on the paste route:
 
 ```
 SPAWN <id> | head <sha> | <n> tests | answers in .caddis/spawn-session/<id>-answers.md
@@ -206,8 +374,12 @@ chat cannot be reviewed**, and cannot be re-read when the next handover asks wha
 | Refusal | Why |
 |---|---|
 | Run with a dirty tree | uncommitted work is invisible to the successor |
+| Run above 95% context | the handover would be written by the faculty that is failing — fluently, with citations, and wrong |
+| Run with no context figure at all | a gate that defaults to proceed is not a gate |
 | Write a commit hash or test count as current state | both went stale within the hour, twice |
 | Write a question whose answer is not in a committed file | it would test memory |
-| Store an answer key | it freezes your belief, and the child can read it |
+| Store an answer key | it freezes your belief, and the child can read it. **`check` enforces this** — see round 1 |
 | Grade your own answers | you validate; the child answers |
+| Close on an unanswered handshake | it is the same as never running one. `handshake close` refuses |
+| Read silence as success | a child that skipped the gate looks exactly like one still reading |
 | Proceed when the open-item count is unknown | that count is the integrity check |

package/bundles/manifest.json

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

package/package.json

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