@caddis/cli 0.2.4 → 0.2.5

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

@@ -14,6 +14,27 @@ issue. This skill runs that second reviewer over the current changes and acts on
 - On a risky diff (auth, crypto, data-touching, concurrency) where a second opinion is cheap insurance.
 - NOT a replacement for the in-repo `/caddis:code-review` — this is the *cross-vendor* complement.
 
+## Check the key FIRST, and ask if it is missing
+
+```bash
+python "$TOOL" --check-config
+```
+
+Exit 0 prints which providers have a key. **Exit 3 means nothing is configured — stop and ask the
+user before reading any diff.** Do not proceed, and do not silently skip the review.
+
+Ask with `AskUserQuestion` which provider to set up, then write the key to `~/.caddis/keys.env` as
+`DEEPSEEK_API_KEY=<key>` (or the matching variable). That file sits outside every git repo, so it
+cannot be committed by accident. **Never put a key in the repo, in a command, or in a reply.**
+
+This used to fail mid-task with a commit pending — the worst moment to go hunting for a credential.
+A command that fails once at an inconvenient moment does not get retried, so the safety check is
+quietly lost and nothing records the loss. The script stays non-interactive because it also runs
+headless, where a stdin prompt hangs instead of asking; the asking is the agent's job.
+
+If a key exists for a *different* provider than the one requested, the error names it and gives the
+exact flag (`--provider glm`). Read the message before concluding anything is missing.
+
 ## Prerequisites (one-time)
 Only the key is mandatory — the tool ships **provider presets** (default `deepseek`, the cheapest + most
 architecturally distinct-from-Claude option; a review costs well under a cent):
@@ -28,16 +49,41 @@ churn — the preset table in `oss_review.py` is the one place to edit a rename,
 `REVIEW_BASE_URL` always win, so you can point at any new id without touching code.
 
 ## How to run
-From the repo root. Locate the tool, in order:
-- `.github/tools/oss_review.py` — this project vendors its own copy.
-- `${CLAUDE_PLUGIN_ROOT}/scripts/oss_review.py` — the plugin-bundled copy (every Claude Code
-  install has this; use it whenever the project has no local copy).
+From the repo root. Resolve the tool path deterministically — check only these two exact
+locations, in order, and **never search the filesystem for it** (see Rules below):
+```bash
+# THE PLUGIN COPY WINS. It is the one `caddis update` refreshes; a vendored copy is a snapshot
+# of whatever caddis shipped the day someone copied it, and it never updates again.
+if [ -f "${CLAUDE_PLUGIN_ROOT}/scripts/oss_review.py" ]; then
+  TOOL="${CLAUDE_PLUGIN_ROOT}/scripts/oss_review.py"
+  # A vendored copy that DIFFERS is a live hazard, not a curiosity — say so, do not stay silent.
+  if [ -f ".github/tools/oss_review.py" ]      && ! diff -q ".github/tools/oss_review.py" "$TOOL" >/dev/null 2>&1; then
+    echo "[cross-review] WARNING: .github/tools/oss_review.py differs from the caddis copy and is"
+    echo "               being IGNORED. Delete it, or keep the local change deliberately."
+  fi
+elif [ -f ".github/tools/oss_review.py" ]; then
+  TOOL=".github/tools/oss_review.py"   # no plugin present — the vendored copy is all there is
+else
+  echo "oss_review.py not found at either known location — report this and stop. Do NOT search for it."
+  exit 3
+fi
 ```
-python <resolved-path>/oss_review.py                       # review the working tree (staged+unstaged)
-python <resolved-path>/oss_review.py --range origin/main..HEAD   # review a branch's commits
+
+> **Why the plugin copy is first.** It used to be second. On 2026-08-10 a repo ran a stale vendored
+> `oss_review.py` and got `REVIEW: CLEAN` on a database write path that was never reviewed. The bug
+> had been fixed on 2026-08-01 — the fix just never reached the caller, because a file someone
+> copied weeks earlier silently won. `caddis_gate.py vendor-drift` now fails on the same condition.
+```
+python "$TOOL"                                             # review the working tree (staged+unstaged)
+python "$TOOL" --range origin/main..HEAD                   # review a branch's commits
 ```
 Optional flags: `--cwd <repo>`, `--base-url <url>`, `--model <id>` (override the env).
 
+**Diff-size ceiling.** A diff over `REVIEW_MAX_DIFF_CHARS` (default 60,000 chars) is **split into batches** on whole-file boundaries and each batch reviewed separately (verdict is CLEAN only if every batch is). Exit 2 now means a *single unsplittable file* over the ceiling, or too many batches — not an ordinary large diff. Previously it was refused with exit 2
+*before* any LLM call — an oversized diff has been observed to come back either an empty response, or
+worse, a `REVIEW: CLEAN` with zero real engagement. If you hit this, narrow `--range` or review in
+smaller chunks; don't just raise `--max-diff-chars` without knowing the endpoint's real limit.
+
 ## Interpret the exit code
 - **0 — REVIEW: CLEAN** → no blocking issues. Proceed.
 - **1 — REVIEW: BLOCKING** → the reviewer found blocking issues. **Read the printed findings, then FIX
@@ -52,3 +98,7 @@ Optional flags: `--cwd <repo>`, `--base-url <url>`, `--model <id>` (override the
   the main thread after reading the findings.
 - Treat exit 2/3 as blocking-unknown, never as approval (the tool is fail-closed by design).
 - Different vendor ⇒ different style; weigh its findings on merit, don't cargo-cult them.
+- **Never use `find`, `Get-ChildItem -Recurse`, or any other filesystem-wide search to locate
+  `oss_review.py`.** Check only the two paths above. On Git Bash under Windows, `find /` (or any
+  search rooted at `/`) walks every mounted drive, not just the repo — it can hang or take minutes.
+  If neither path exists, stop and report it; don't go hunting for the file.

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

@@ -58,7 +58,7 @@ HEAD_SHA=$(git rev-parse HEAD)
 
 [Dispatch superpowers:code-reviewer subagent]
   WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
-  PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md
+  PLAN_OR_REQUIREMENTS: Task 2 from .caddis/plans/deployment-plan.md
   BASE_SHA: a7981ec
   HEAD_SHA: 3df7661
   DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types

package/bundles/antigravity-plugin-extras/skills/schema-migration/SKILL.md

@@ -24,7 +24,7 @@ Systematically migrate an application from a legacy database schema to a new sch
 1. **Read-Only** — Never execute DDL or DML (`CREATE`, `ALTER`, `INSERT`, `UPDATE`, `DELETE`) against the database. All analysis is SELECT-only.
 2. **No SQL Aliases** — Proposed queries must use direct `Table.Column` notation. Aliases obscure the mapping and make future changes harder to trace.
 3. **No Assumptions** — Every column mapping must be verified against the actual schema DDL. If a mapping is ambiguous or a source column has no clear target, flag it as a **GAP** rather than guessing.
-4. **Scratchpad Protocol** — If context becomes large, save intermediate findings to `.github/plans/temp_migration_scratchpad.md` to preserve state across reasoning steps.
+4. **Scratchpad Protocol** — If context becomes large, save intermediate findings to `.caddis/plans/temp_migration_scratchpad.md` to preserve state across reasoning steps.
 
 ---
 
@@ -255,7 +255,7 @@ Produce a single, comprehensive document suitable for use as an **Implementation
 ```
 
 ### Output Location
-Place the final report at the path specified by the user (default: `.github/plans/backlog/migration_report.md`).
+Place the final report at the path specified by the user (default: `.caddis/agent-docs/migration_report.md` — it is an agent-produced report, not a backlog item).
 
 ---
 

package/bundles/antigravity-plugin-extras/skills/state-tracking/SKILL.md

@@ -23,7 +23,7 @@ State tracking uses two distinct documents with different write semantics:
 
 | Document | Write mode | Purpose |
 |----------|-----------|---------|
-| **Plan Tracker** (`.github/plans/tracker/<slug>-tracker.md`) | Overwrite each row | Per-phase completion record, linked to commits |
+| **Plan Tracker** (`.caddis/plans/tracker/<slug>-tracker.md`) | Overwrite each row | Per-phase completion record, linked to commits |
 | **CURRENT_STATE** (`.github/agent-docs/CURRENT_STATE.md`) | Overwrite head section | Single-view of right now: what phase, what's done, what's blocked |
 | **Session Log** (inline in CURRENT_STATE, append-only) | Append only | Chronological audit trail — never rewrite past entries |
 
@@ -42,8 +42,8 @@ Replace this section wholesale each time:
 ```markdown
 ## Current Status
 
-**Plan:** `.github/plans/<feature-slug>.md`
-**Tracker:** `.github/plans/tracker/<feature-slug>-tracker.md`
+**Plan:** `.caddis/plans/<feature-slug>.md`
+**Tracker:** `.caddis/plans/tracker/<feature-slug>-tracker.md`
 **Last updated:** YYYY-MM-DDTHH:MM:SSZ
 **Active agent:** @[Agent] (model: [Model])
 **Current phase:** Phase N — [Name]
@@ -116,7 +116,7 @@ The canonical template is at `.github/agent-docs/CURRENT_STATE.md`. Copy it for
 ## Integration with Golden-Plan
 
 When running a golden-plan:
-- The plan tracker (`.github/plans/tracker/<slug>-tracker.md`) is the commitment ledger.
+- The plan tracker (`.caddis/plans/tracker/<slug>-tracker.md`) is the commitment ledger.
 - CURRENT_STATE.md is the working scratch-pad for the current session.
 - After completing a phase, update BOTH the tracker row AND the CURRENT_STATE current-status section.
 - When all tracker rows are `Complete`, follow the Plan Completion Protocol in golden-plan: move the plan to `plans/done/`, set `status: done`.

package/bundles/manifest.json

@@ -1,7 +1,7 @@
 {
-  "poolVersion": "1.3.54",
+  "poolVersion": "1.3.74",
   "bundles": {
-    "antigravity-plugin": "1.3.54",
-    "antigravity-plugin-extras": "1.3.20"
+    "antigravity-plugin": "1.3.74",
+    "antigravity-plugin-extras": "1.3.24"
   }
 }

package/dist/cli.js

@@ -4527,6 +4527,32 @@ var init_drive = __esm({
   }
 });
 
+// src/util/semver.ts
+function compareVersions(a, b3) {
+  const pa = parse(a);
+  const pb = parse(b3);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+    const da = pa[i] ?? 0;
+    const db = pb[i] ?? 0;
+    if (da > db) return 1;
+    if (da < db) return -1;
+  }
+  return 0;
+}
+function parse(v) {
+  if (!v || v === "unknown") return null;
+  const core = v.trim().replace(/^v/, "").split(/[-+]/)[0] ?? "";
+  const parts = core.split(".");
+  if (parts.length === 0 || parts.some((p2) => p2 === "" || !/^\d+$/.test(p2))) return null;
+  return parts.map((p2) => Number.parseInt(p2, 10));
+}
+var init_semver = __esm({
+  "src/util/semver.ts"() {
+    "use strict";
+  }
+});
+
 // src/commands/report.ts
 async function checkCliUpdate(currentVersion) {
   const result = await run("npm", ["view", "@caddis/cli", "version"], { timeout: 5e3 });
@@ -4541,7 +4567,10 @@ function classify(adapter, detection, status4, poolVersion) {
   if (!status4.installed) return "missing";
   if (!status4.version) return "unknown";
   if (poolVersion === "unknown") return "unknown";
-  return status4.version === poolVersion ? "current" : "stale";
+  const order = compareVersions(status4.version, poolVersion);
+  if (order === null) return status4.version === poolVersion ? "current" : "stale";
+  if (order === 0) return "current";
+  return order > 0 ? "ahead" : "stale";
 }
 async function gather(adapters, options = {}) {
   const manifest = bundleManifest();
@@ -4578,6 +4607,7 @@ function actionable(report, includeCurrent = false) {
   return report.agents.filter((entry) => {
     if (!entry.detection.present || !entry.adapter.supported) return false;
     if (includeCurrent) return true;
+    if (entry.drift === "ahead") return false;
     return entry.drift !== "current" || entry.extrasDrift === "stale" || entry.extrasDrift === "unknown";
   });
 }
@@ -4586,6 +4616,7 @@ var init_report = __esm({
     "use strict";
     init_exec();
     init_pkg();
+    init_semver();
   }
 });
 
@@ -4671,10 +4702,18 @@ async function update(options) {
   const targets = actionable(report, options.force === true);
   if (targets.length === 0) {
     const supportedPresent = report.agents.filter((e2) => e2.detection.present && e2.adapter.supported);
+    const ahead = report.agents.filter((e2) => e2.drift === "ahead");
     line("");
-    line(
-      supportedPresent.length === 0 ? `  ${color.yellow("No supported agent found.")} caddis v0.1 drives Claude Code and agy.` : `  ${color.green("Everything is already current.")} Use --force to re-drive anyway.`
-    );
+    if (supportedPresent.length === 0) {
+      line(`  ${color.yellow("No supported agent found.")} caddis v0.1 drives Claude Code and agy.`);
+    } else if (ahead.length > 0) {
+      line(
+        `  ${color.green("Nothing to do.")} ${ahead.length} agent(s) are NEWER than this package's bundled pool (${report.poolVersion}) \u2014 driving them would be a DOWNGRADE, so they were left alone.`
+      );
+      line(`  Update the CLI itself (${color.cyan("npm i -g @caddis/cli")}), or ${color.cyan("--force")} to roll back deliberately.`);
+    } else {
+      line(`  ${color.green("Everything is already current.")} Use --force to re-drive anyway.`);
+    }
     return 0;
   }
   line("");
@@ -4805,6 +4844,7 @@ function renderSummary(report, findings) {
 function markFor(drift) {
   switch (drift) {
     case "current":
+    case "ahead":
       return "ok";
     case "stale":
     case "missing":
@@ -4820,6 +4860,8 @@ function describe(entry, poolVersion) {
   switch (entry.drift) {
     case "current":
       return `caddis ${entry.status.version} ${color.dim("(current)")}`;
+    case "ahead":
+      return `caddis ${color.green(entry.status.version ?? "?")} ${color.dim("\u2014 newer than this CLI bundles")} ${color.dim(`(${poolVersion}); left alone, update @caddis/cli to catch up`)}`;
     case "stale":
       return `caddis ${color.yellow(entry.status.version ?? "?")} ${color.dim("\u2192")} ${color.bold(poolVersion)} available`;
     case "unknown":
@@ -4986,10 +5028,17 @@ async function status3(options) {
   const stale = report.agents.filter(
     (entry) => entry.drift === "stale" || entry.drift === "missing" || entry.extrasDrift === "stale"
   );
+  const ahead = report.agents.filter((entry) => entry.drift === "ahead");
   if (stale.length > 0) {
     line(`  ${color.yellow(`${stale.length} agent(s) behind`)} \u2014 run ${color.cyan("caddis update")} (or ${color.cyan("caddis doctor")} for detail)`);
     line("");
   }
+  if (ahead.length > 0) {
+    line(
+      `  ${ahead.length} agent(s) are NEWER than this CLI's bundled pool (${report.poolVersion}) \u2014 left alone. Update the CLI itself (${color.cyan("npm i -g @caddis/cli")}) to catch up.`
+    );
+    line("");
+  }
   return 0;
 }
 function toRow(entry) {
@@ -5010,6 +5059,8 @@ function stateLabel(drift, disabled) {
       return disabled ? color.yellow("current, disabled") : color.green("current");
     case "stale":
       return color.yellow("update available");
+    case "ahead":
+      return color.green("newer than CLI pool");
     case "unknown":
       return color.yellow("version unknown");
     case "missing":

package/package.json

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