@caddis/cli 0.2.3 → 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.47",
+  "poolVersion": "1.3.74",
   "bundles": {
-    "antigravity-plugin": "1.3.47",
-    "antigravity-plugin-extras": "1.3.20"
+    "antigravity-plugin": "1.3.74",
+    "antigravity-plugin-extras": "1.3.24"
   }
 }

package/dist/cli.js

@@ -3473,6 +3473,51 @@ var require_commander = __commonJS({
   }
 });
 
+// src/util/exec.ts
+async function run(cmd, args, opts = {}) {
+  const { execa } = await import("execa");
+  try {
+    const result = await execa(cmd, args, {
+      cwd: opts.cwd,
+      timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS,
+      env: opts.env,
+      reject: false,
+      all: false,
+      stripFinalNewline: true,
+      // Windows: resolve .cmd/.ps1 shims through the shell-less path lookup
+      // execa already does, but be explicit that we are not using a shell.
+      shell: false,
+      windowsHide: true
+    });
+    return {
+      ok: result.exitCode === 0 && !result.failed,
+      code: result.exitCode ?? null,
+      stdout: String(result.stdout ?? ""),
+      stderr: String(result.stderr ?? ""),
+      failure: result.failed && result.exitCode === void 0 ? result.shortMessage : void 0
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      code: null,
+      stdout: "",
+      stderr: "",
+      failure: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function formatCommand(cmd, args) {
+  const quoted = args.map((a) => /\s/.test(a) ? `"${a}"` : a);
+  return [cmd, ...quoted].join(" ");
+}
+var DEFAULT_TIMEOUT_MS;
+var init_exec = __esm({
+  "src/util/exec.ts"() {
+    "use strict";
+    DEFAULT_TIMEOUT_MS = 12e4;
+  }
+});
+
 // node_modules/isexe/dist/commonjs/index.min.js
 var require_index_min = __commonJS({
   "node_modules/isexe/dist/commonjs/index.min.js"(exports) {
@@ -4482,33 +4527,73 @@ 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 });
+  if (!result.ok) return null;
+  const latest = result.stdout.trim();
+  if (!latest || latest === currentVersion) return null;
+  return { current: currentVersion, latest };
+}
 function classify(adapter, detection, status4, poolVersion) {
   if (!detection.present) return "absent";
   if (!adapter.supported) return "unsupported";
   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) {
+async function gather(adapters, options = {}) {
   const manifest = bundleManifest();
   const poolVersion = manifest.poolVersion;
   const extrasVersion = manifest.bundles["antigravity-plugin-extras"];
-  const agents = await Promise.all(
-    adapters.map(async (adapter) => {
-      const detection = await adapter.detect();
-      const status4 = detection.present ? await adapter.status() : { installed: false, note: "agent not installed" };
-      return {
-        adapter,
-        detection,
-        status: status4,
-        drift: classify(adapter, detection, status4, poolVersion),
-        extrasDrift: classifyExtras(adapter, detection, status4, extrasVersion)
-      };
-    })
-  );
-  return { cliVersion: packageInfo().version, poolVersion, extrasVersion, agents };
+  const cliVersion = packageInfo().version;
+  const [agents, cliUpdate] = await Promise.all([
+    Promise.all(
+      adapters.map(async (adapter) => {
+        const detection = await adapter.detect();
+        const status4 = detection.present ? await adapter.status() : { installed: false, note: "agent not installed" };
+        return {
+          adapter,
+          detection,
+          status: status4,
+          drift: classify(adapter, detection, status4, poolVersion),
+          extrasDrift: classifyExtras(adapter, detection, status4, extrasVersion)
+        };
+      })
+    ),
+    options.checkCliUpdate ? checkCliUpdate(cliVersion) : Promise.resolve(null)
+  ]);
+  return { cliVersion, poolVersion, extrasVersion, agents, cliUpdate: cliUpdate ?? void 0 };
 }
 function classifyExtras(adapter, detection, status4, extrasVersion) {
   if (!status4.extras) return void 0;
@@ -4522,13 +4607,16 @@ 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";
   });
 }
 var init_report = __esm({
   "src/commands/report.ts"() {
     "use strict";
+    init_exec();
     init_pkg();
+    init_semver();
   }
 });
 
@@ -4614,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("");
@@ -4646,7 +4742,7 @@ __export(doctor_exports, {
 import os3 from "os";
 import process2 from "process";
 async function doctor(options) {
-  const report = await gather(options.adapters);
+  const report = await gather(options.adapters, { checkCliUpdate: true });
   const findings = [];
   if (options.json) {
     line(JSON.stringify(toJson(report), null, 2));
@@ -4667,7 +4763,17 @@ function renderEnvironment(report, problems) {
     problems.push({ kind: "problem", text: `node ${process2.versions.node} is below the required ${REQUIRED_NODE_MAJOR}.${REQUIRED_NODE_MINOR}`, fix: "upgrade node" });
   }
   item("info", `platform ${process2.platform} ${process2.arch} (${os3.release()})`);
-  item("info", `@caddis/cli ${report.cliVersion}`);
+  if (report.cliUpdate) {
+    item("warn", `@caddis/cli ${report.cliVersion} ${color.dim("\u2192")} ${color.bold(report.cliUpdate.latest)} available`);
+    detail("everything below is compared against the pool THIS install carries, which is now behind the published one");
+    problems.push({
+      kind: "problem",
+      text: `@caddis/cli itself is behind: ${report.cliUpdate.current} installed, ${report.cliUpdate.latest} published`,
+      fix: "npm i -g @caddis/cli@latest"
+    });
+  } else {
+    item("ok", `@caddis/cli ${report.cliVersion}`);
+  }
   const manifest = bundleManifest();
   if (report.poolVersion === "unknown") {
     item("fail", "shipped pool version unknown");
@@ -4738,6 +4844,7 @@ function renderSummary(report, findings) {
 function markFor(drift) {
   switch (drift) {
     case "current":
+    case "ahead":
       return "ok";
     case "stale":
     case "missing":
@@ -4753,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":
@@ -4837,6 +4946,7 @@ function problemFor(entry, poolVersion) {
 function toJson(report) {
   return {
     cliVersion: report.cliVersion,
+    cliUpdate: report.cliUpdate ?? null,
     poolVersion: report.poolVersion,
     extrasVersion: report.extrasVersion ?? null,
     node: process2.versions.node,
@@ -4918,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) {
@@ -4942,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":
@@ -4990,44 +5109,8 @@ var {
   Help
 } = import_index.default;
 
-// src/util/exec.ts
-var DEFAULT_TIMEOUT_MS = 12e4;
-async function run(cmd, args, opts = {}) {
-  const { execa } = await import("execa");
-  try {
-    const result = await execa(cmd, args, {
-      cwd: opts.cwd,
-      timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS,
-      env: opts.env,
-      reject: false,
-      all: false,
-      stripFinalNewline: true,
-      // Windows: resolve .cmd/.ps1 shims through the shell-less path lookup
-      // execa already does, but be explicit that we are not using a shell.
-      shell: false,
-      windowsHide: true
-    });
-    return {
-      ok: result.exitCode === 0 && !result.failed,
-      code: result.exitCode ?? null,
-      stdout: String(result.stdout ?? ""),
-      stderr: String(result.stderr ?? ""),
-      failure: result.failed && result.exitCode === void 0 ? result.shortMessage : void 0
-    };
-  } catch (error) {
-    return {
-      ok: false,
-      code: null,
-      stdout: "",
-      stderr: "",
-      failure: error instanceof Error ? error.message : String(error)
-    };
-  }
-}
-function formatCommand(cmd, args) {
-  const quoted = args.map((a) => /\s/.test(a) ? `"${a}"` : a);
-  return [cmd, ...quoted].join(" ");
-}
+// src/agents/claude.ts
+init_exec();
 
 // src/util/which.ts
 var import_which = __toESM(require_lib(), 1);
@@ -5167,6 +5250,7 @@ var claudeAdapter = {
 };
 
 // src/agents/agy.ts
+init_exec();
 import { readFileSync as readFileSync2, existsSync as existsSync2, mkdtempSync, cpSync, rmSync } from "fs";
 import os from "os";
 import path2 from "path";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caddis/cli",
-  "version": "0.2.3",
+  "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",