@caddis/cli 0.4.8 → 0.4.9

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

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

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.95",
+  "version": "1.3.96",
   "description": "caddis — agent-agnostic dev harness as an Antigravity (agy) plugin: TDD skills + commands, single-sourced with the Claude Code plugin."
 }

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

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

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

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

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

@@ -87,6 +87,7 @@ Record the outcome in relay.md's `## Learnings captured` line (below).
 
 ## Step 2c — was any of it the harness?
 
+<!-- shared:harness-friction-question — keep byte-identical across commands; a test pins it -->
 **One question, asked here because here is where you are already reflecting.** The observations
 that reach caddis today are the ones someone happened to recall days later — so small, frequent
 friction never arrives, which is exactly the friction worth fixing.
@@ -99,6 +100,7 @@ harness, not this repo.
 ```
 
 Nothing to say is the normal answer. Say nothing and move on — this must not become a ritual.
+<!-- /shared:harness-friction-question -->
 
 ## Step 3 — write the resume doc (overwrite) with exactly these sections
 > **Where to write:** solo / single active branch → `.caddis/relay.md` (default).

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

@@ -46,6 +46,7 @@ surface the `[DOC-MAP]` "read the index first" pointer for future sessions in th
 
 ## Step 5 — was any of it the harness?
 
+<!-- shared:harness-friction-question — keep byte-identical across commands; a test pins it -->
 **One question, asked here because here is where you are already reflecting.** The observations
 that reach caddis today are the ones someone happened to recall days later — so small, frequent
 friction never arrives, which is exactly the friction worth fixing.
@@ -58,6 +59,7 @@ harness, not this repo.
 ```
 
 Nothing to say is the normal answer. Say nothing and move on — this must not become a ritual.
+<!-- /shared:harness-friction-question -->
 
 ## KB note format (OKF-lite — mandatory for every new note)
 
@@ -83,7 +85,7 @@ generated: { by: caddis/<model-id>, at: 2026-07-28T09:00:00Z }
 
 The full schema, the caddis↔OKF `status` mapping, and what caddis deliberately skips from OKF v0.2
 (`sources:`, `Attested Computation`) live in
-[`.github/instructions/document-frontmatter.instructions.md`](../../.github/instructions/document-frontmatter.instructions.md).
+`.github/instructions/document-frontmatter.instructions.md` in the caddis source repo. (Not a link: a relative path out of the plugin directory resolves nowhere once installed.)
 
 **Backward compatible:** an existing note with no trust fields is still correct. Do not bulk-migrate
 old notes — add the fields as notes are next touched.

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

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

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

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

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

@@ -46,6 +46,7 @@ Use conventional commits: `fix:`, `feat:`, `chore:`, `refactor:`, `docs:`. Scope
 
 **2b. CROSS-REVIEW TRIGGER** — `ship` has no review pause at all, which is how sixteen fixes reached production unreviewed in one day.
 
+<!-- shared:cross-review-trigger — keep byte-identical across commands; a test pins it -->
 **Run the trigger, do not eyeball the diff:**
 
 ```bash
@@ -60,6 +61,7 @@ gets switched off inside a week.
 It fires on SQL and repositories, `services/`, caches and refresh jobs, auth and RBAC, or a diff
 over 400 changed lines. No judgement in any of those — deliberately, because judgement is exactly
 what failed.
+<!-- /shared:cross-review-trigger -->
 
 **3. PUSH** — to the repo's default branch (confirm the branch first; don't assume `main`):
 ```

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

@@ -52,6 +52,7 @@ are uncommitted.)
 
 ## Step 3b — Cross-review trigger (before anything is pushed)
 
+<!-- shared:cross-review-trigger — keep byte-identical across commands; a test pins it -->
 **Run the trigger, do not eyeball the diff:**
 
 ```bash
@@ -66,6 +67,7 @@ gets switched off inside a week.
 It fires on SQL and repositories, `services/`, caches and refresh jobs, auth and RBAC, or a diff
 over 400 changed lines. No judgement in any of those — deliberately, because judgement is exactly
 what failed.
+<!-- /shared:cross-review-trigger -->
 
 > **Why this is mechanical and not "consider a review here".** serve-sight shipped four
 > production releases in one day — sixteen fixes across SQL, caches, refresh jobs and React — and

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

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

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

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

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

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

package/bundles/manifest.json

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

package/package.json

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